dsh-ensp 0.2.0 → 0.3.0

package/README.md

@@ -25,6 +25,8 @@
 
 生成 eNSP 可直接打开并正常显示的 `.topo` 文件。支持内置场景，也可自定义设备与链路。
 
+支持的机型来自 `src/core/models.mjs` 的一张表，其中 16 个机型各有测过的接口布局。`Router` 和 `Client` 是教学实验里常见的两个老机型：eNSP 自带的 40 个样例里一次都没出现，所以早期版本的表漏掉了它们，而实际课程作业里它们占了 43/190 台设备。解析拓扑时，端口名优先按设备自己声明的 `<interface>` 块算——实验里加装串口卡之后，扁平索引 3 在同一型号上可以是 `Serial0/0/0`，也可以不是。
+
 ```js
 import { twoPcLab, writeTopology } from 'dsh-ensp'
 
@@ -199,6 +201,8 @@ accepted: 2/2 checks passed
 
 约 30 个场景有专门写的断言（OSPF 要 `Full`、BGP 要 `Established`、VRRP 要有 `Master`/`Backup`、MPLS VPN 要有 `Established` 与 VPN 路由表），其余场景回退成“把场景里提到的验证命令都跑一遍”的冒烟检查。判定逻辑在 `src/core/acceptance.mjs` 的 `EXPECTATIONS`，断言支持 `contains`、`notContains`、`matches`、`minLines`。对应的工具是 `ensp_verify`，`ensp_scenario` 会告诉某个场景有没有专门断言。
 
+断言里的设备名按角色对应到你实际的拓扑：蓝图叫 `R1`/`R2`，而下载来的课程作业可能叫 `RA`/`RB`/`RC`，校验时会取第一台有控制台的设备（`R2` 取第二台），不会因为名字不同就报“找不到设备”。
+
 断言不通过时会自己重试，因为路由协议是在命令返回之后才收敛的。`ensp apply` 一结束就验收，OSPF 邻居通常还在 `ExStart` 或 `2-Way`，只取一次快照会把它报成坏的实验。默认给 60 秒（`--wait` 改），通过时会注明等了多久：
 
 ```console

package/docs/ENSP-FORMAT.md

@@ -95,6 +95,21 @@ shows an empty canvas with **no error message**.
 | `MCS` | `Ethernet/Ethernet×1` | 1 | 1 |
 | `Cloud` | `Ethernet/Ethernet×3`, `Ethernet/GE×0`, `Serial/Serial×0` | 3 | 4 |
 | `FRSW` | `Serial/Serial×16` | 16 | 1 |
+| `Router` | `Ethernet/Ethernet×2`, `Ethernet/GE×4`, `Serial/Serial×4` | 10 | 43 |
+| `Client` | `Ethernet/Ethernet×1` | 1 | 4 |
+
+`Router` and `Client` were counted on the 18-topology teaching corpus (190 devices,
+185 links) rather than on the bundled samples, where they never appear. Both are
+`isplugin="0"` in `res/items.xml`, so they ship with every eNSP install; the
+`Router` entry does say `eNSP don't maintained this device any more, just keep it.`
+The CLI name order was confirmed on a live device: `display interface brief` lists
+`Ethernet0/0/0..1`, `GigabitEthernet0/0/0..3`, `Serial0/0/0..3`, `NULL0`.
+
+> **A device may add cards, so read its own declarations.** A NAT lab in that
+> corpus mounts a serial card on an AR2220: flat index 3 is `Serial0/0/0` there and
+> `GigabitEthernet0/0/3` on a stock unit. `parseTopology` therefore builds the port
+> list from each `<dev>`'s `<interface>` block and only falls back to the model
+> table when a file declares nothing.
 
 > **`PC` declares `interfacename="GE"`, not `"Ethernet"`.** An earlier version of
 > this project wrote `Ethernet` for PCs on the theory that a PC has one Ethernet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ensp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Automate Huawei eNSP labs: generate .topo files, start and stop devices, and push configuration one command at a time with per-command error reporting.",
   "keywords": [
     "dsh",

package/src/core/acceptance.mjs

@@ -169,6 +169,25 @@ export function evaluateAssertion(output, expect = {}) {
   }
 }
 
+/**
+ * Resolve a curated check's device name against the devices that actually exist.
+ *
+ * Curated plans name devices the way the shipped blueprints do: R1, R2, R3. A lab
+ * built from somebody else's topology calls them RA/RB/RC, LSW1/LSW2, or anything
+ * at all. Reporting `no console port for device "R1"` on a healthy lab is worse
+ * than useless, so fall back to the device that plays the same role: the number in
+ * the name picks the position (R1 first, R2 second), and a name without a number
+ * picks the first console device.
+ */
+export function resolveDevice(on, available = []) {
+  const names = [...available].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }))
+  if (!names.length) return on
+  if (names.includes(on)) return on
+  const numbered = /(\d+)$/.exec(on)
+  const index = numbered ? Math.max(0, Number(numbered[1]) - 1) : 0
+  return names[Math.min(index, names.length - 1)]
+}
+
 /**
  * Build the acceptance plan for a scenario.
  *
@@ -185,7 +204,7 @@ export function planFor(id, { devices } = {}) {
       scenario: id,
       title: scenario.title,
       source: 'curated',
-      checks: curated.map((c) => ({ ...c, kind: 'assert' })),
+      checks: curated.map((c) => ({ ...c, on: resolveDevice(c.on, devices), kind: 'assert' })),
     }
   }
   const first = (devices && devices.length && devices[0]) || scenario.devices?.split(/[、,，\s]+/)[0]

package/src/core/console.mjs

@@ -36,6 +36,18 @@ const ERROR_RE =
 /** A `[Y/N]`-style confirmation waiting for an answer. */
 const CONFIRM_RE = /(?:\[Y\/N\]|\(y\/n\)|\[y\/n\]|continue\?|Are you sure)/i
 
+/**
+ * VRP's pager marker. `screen-length 0 temporary` normally turns paging off, but
+ * it is a user-view command: issued from a sub-view it is rejected, and on some
+ * builds it is rejected even in user view. When the pager is still on, a long
+ * `display` command stops at this marker and the rest of the output is simply
+ * missing — which reads as "the configuration is not there" when it is.
+ */
+const PAGER_RE = /---- More ----\s*$/
+
+/** Cap the number of pages we will advance for one command. */
+const MAX_PAGES = 200
+
 const VIEW = {
   user: 'user',
   system: 'system',
@@ -91,6 +103,50 @@ export function hostnameOf(prompt) {
   return inner
 }
 
+/**
+ * Does this transcript end on a pager stop rather than a prompt?
+ *
+ * Exported because "the output stops at `---- More ----`" is the difference
+ * between "the device has nothing more to say" and "we are about to lose the rest
+ * of the answer", and that distinction deserves a test of its own.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function hasPagerMarker(text) {
+  return PAGER_RE.test(String(text ?? '').trimEnd())
+}
+
+/**
+ * Remove pager markers from a transcript collected across several pages.
+ *
+ * VRP prints `---- More ----` where the page broke and then continues on the next
+ * page. The continuation is kept as its own line: page breaks land on line
+ * boundaries in practice, and a spurious break inside a line is harmless, while
+ * gluing two lines together would corrupt `^keyword` style assertions.
+ *
+ * This is only a fallback: {@link ConsoleSession#prepare} normally turns paging
+ * off before any output is read.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function stitchPages(text) {
+  const out = []
+  for (const line of text.split('\n')) {
+    const m = line.match(/^(.*?)---- More ----(.*)$/)
+    if (!m) {
+      out.push(line)
+      continue
+    }
+    const head = m[1].trimEnd()
+    if (head) out.push(head)
+    const tail = m[2].trimStart()
+    if (tail) out.push(tail)
+  }
+  return out.join('\n')
+}
+
 /** Strip ANSI escapes and trailing whitespace from a transcript chunk. */
 function clean(text) {
   return text
@@ -191,7 +247,9 @@ export class ConsoleSession {
       const text = clean(this.#buf)
       // A confirmation question wins over a stale prompt: answer it explicitly.
       if (CONFIRM_RE.test(text.split('\n').slice(-3).join('\n'))) break
-      if (PROMPT_RE.test(text)) {
+      // A pager stop is a terminal state too: nothing more will arrive until we
+      // send a key, so waiting for a prompt here would burn the whole timeout.
+      if (PROMPT_RE.test(text) || PAGER_RE.test(text.trimEnd())) {
         const before = this.#buf.length
         await this.#waitUntil(() => this.#buf.length !== before || this.#closed, settleMs)
         if (this.#buf.length === before) break
@@ -199,7 +257,7 @@ export class ConsoleSession {
         // Poll the buffer rather than sleeping a fixed slice: most commands reply
         // in a few milliseconds, and waiting 200 ms per line dominates the runtime
         // of a 300-line config.
-        await this.#waitUntil(() => PROMPT_RE.test(clean(this.#buf)) || this.#closed, 25)
+        await this.#waitUntil(() => PROMPT_RE.test(clean(this.#buf)) || PAGER_RE.test(clean(this.#buf).trimEnd()) || this.#closed, 25)
       }
     }
     const text = clean(this.#buf)
@@ -260,6 +318,20 @@ export class ConsoleSession {
       output += await this.#readToPrompt(timeoutMs)
     }
 
+    // Walk the pager to the end. A page ends at `---- More ----` with no prompt,
+    // so the command is not finished and the remaining output would be lost.
+    let pages = 0
+    while (PAGER_RE.test(output.trimEnd()) && pages < MAX_PAGES && !this.#closed) {
+      pages += 1
+      this.#buf = ''
+      this.writeRaw(' ')
+      output += await this.#readToPrompt(timeoutMs)
+    }
+    // The marker sits inline where the page broke: VRP prints `---- More ----`
+    // followed by the rest of the line it interrupted. Stitch that tail back onto
+    // the previous line so the caller sees what paging disabled would have shown.
+    if (pages > 0) output = stitchPages(output)
+
     const errorMatch = output.match(ERROR_RE)
     const prompt = this.#prompt
     return {
@@ -311,10 +383,15 @@ export class ConsoleSession {
 
   /**
    * Enable command paging off so long `display` output arrives in one piece.
-   * Failures are non-fatal: some older VRP builds reject the command.
+   *
+   * Failures are non-fatal on purpose: `screen-length 0 temporary` is a user-view
+   * command and is rejected from a sub-view, and some builds reject it outright.
+   * `exec` pages through `---- More ----` stops on its own, so the only cost of a
+   * rejection here is a few extra round trips.
    */
   async prepare() {
-    await this.exec('screen-length 0 temporary', { timeoutMs: 8000 })
+    if (!this.#prompt) await this.prime()
+    if (this.view === VIEW.user) await this.exec('screen-length 0 temporary', { timeoutMs: 8000 })
     return this
   }
 

package/src/core/doctor.mjs

@@ -109,20 +109,32 @@ export function probeInputInjection({ timeoutMs = 30000 } = {}) {
   }
 }
 
-/** Free physical memory in MB, or null when it cannot be read. */
+/**
+ * Free physical memory in MB, or null when it cannot be read.
+ *
+ * On Windows Win32_OperatingSystem is the accurate number, but it needs
+ * PowerShell. Everything else (and any Windows box where PowerShell is not on
+ * PATH) falls back to os.freemem(), so the check still says something useful
+ * instead of giving up on the platform it happens to run on.
+ */
 export function freeMemoryMb() {
-  const r = spawnSync(
-    'powershell',
-    [
-      '-NoProfile',
-      '-Command',
-      "Get-CimInstance Win32_OperatingSystem | ForEach-Object { [int]($_.FreePhysicalMemory / 1024) }",
-    ],
-    { encoding: 'utf8', windowsHide: true, timeout: 20000 },
-  )
-  if (r.status !== 0) return null
-  const n = Number((r.stdout || '').trim())
-  return Number.isFinite(n) && n > 0 ? n : null
+  if (process.platform === 'win32') {
+    const r = spawnSync(
+      'powershell',
+      [
+        '-NoProfile',
+        '-Command',
+        "Get-CimInstance Win32_OperatingSystem | ForEach-Object { [int]($_.FreePhysicalMemory / 1024) }",
+      ],
+      { encoding: 'utf8', windowsHide: true, timeout: 20000 },
+    )
+    if (r.status === 0) {
+      const n = Number((r.stdout || '').trim())
+      if (Number.isFinite(n) && n > 0) return n
+    }
+  }
+  const fallback = Math.floor(os.freemem() / (1024 * 1024))
+  return Number.isFinite(fallback) && fallback > 0 ? fallback : null
 }
 
 /** Ports in eNSP's console range that are already listening. */
@@ -244,7 +256,14 @@ export function doctor(options = {}) {
   // 6. Memory headroom: each AR_Base needs 256 MB, WLAN images 530-650 MB
   const free = freeMemoryMb()
   if (free === null) {
-    checks.push(check('memory', 'warn', 'could not read free physical memory'))
+    checks.push(
+      check(
+        'memory',
+        'warn',
+        'could not read free physical memory',
+        'Check free memory yourself (Task Manager on Windows) and keep at least 1 GB spare; a device needs ~256 MB to boot.',
+      ),
+    )
   } else {
     const okMem = free >= MIN_FREE_MEMORY_MB
     checks.push(

package/src/core/index.mjs

@@ -16,6 +16,8 @@ export {
   flatIndexToVrp,
   portCount,
   describePorts,
+  portsFromDeclarations,
+  declarationsFor,
 } from './models.mjs'
 
 // Kept for consumers written against the old shape; the table behind it was
@@ -76,13 +78,14 @@ export {
   EXPECTATIONS,
   evaluateAssertion,
   planFor,
+  resolveDevice,
   hasChecks,
   consolePorts,
   runAcceptance,
   formatAcceptance,
 } from './acceptance.mjs'
 
-export { ConsoleSession, openConsole, probeConsole, viewOf, hostnameOf } from './console.mjs'
+export { ConsoleSession, openConsole, probeConsole, viewOf, hostnameOf, hasPagerMarker } from './console.mjs'
 
 export {
   enspPid,

package/src/core/launcher.mjs

@@ -814,8 +814,15 @@ export async function startAllDevices({
   }
 
   report({ phase: 'calibrate', hwnd })
-  // Calibration photographs the screen, so an occluded window yields anchors
-  // measured on the wrong pixels. Check first, and say who is in the way.
+  // Bringing the window forward and photographing it are the same problem seen
+  // twice: calibration reads pixels off the screen, so it has to happen while
+  // eNSP is actually in front. Focus first, then ask who owns the toolbar point.
+  // 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 })
+  let focused = focusEnsp(hwnd)
+  if (focused) await new Promise((resolve) => setTimeout(resolve, 300))
+
   const occlusion = checkOcclusion(hwnd)
   if (occlusion.occluded) {
     throw new Error(
@@ -843,9 +850,12 @@ export async function startAllDevices({
   }
   report({ phase: 'calibrated', method: anchors.method, detail: anchors.detail })
 
-  report({ phase: 'focus', hwnd })
-  const focused = focusEnsp(hwnd)
-  if (!focused) report({ phase: 'focus-failed', hwnd })
+  // The window was raised before calibration; re-raise it in case photographing
+  // the screen or the terminal regaining focus pushed it back down.
+  if (!focused) {
+    focused = focusEnsp(hwnd)
+    if (!focused) report({ phase: 'focus-failed', hwnd })
+  }
 
   report({ phase: 'click', button: 'start', anchor: anchors.start })
   const click = clickToolbar(hwnd, { button: 'start', anchors })

package/src/core/models.mjs

@@ -76,6 +76,29 @@ export const MODEL_SPECS = {
     vrp: 'GigabitEthernet0/0/',
     console: true,
   },
+  // Lab builds from teaching material (the 18 ICVE topologies) use the legacy
+  // `Router` model far more than any AR: 43 of 190 devices. Its port list is two
+  // fast Ethernet, four gigabit, four serial ports, and the CLI keeps the same
+  // order — verified by booting one and reading `display interface brief`.
+  // `Router` and `Client` are `isplugin="0"` in eNSP's items.xml, so they are
+  // built in; a machine "missing" them is not out of date.
+  Router: {
+    groups: [
+      ['Ethernet', 'Ethernet', 2, 0, 'Ethernet0/0/'],
+      ['Ethernet', 'GE', 4, 0],
+      ['Serial', 'Serial', 4, 0, 'Serial0/0/'],
+    ],
+    base: 0,
+    vrp: 'Ethernet0/0/',
+    console: true,
+  },
+  // A web client: one Ethernet port, no console.
+  Client: {
+    groups: [['Ethernet', 'Ethernet', 1, 0, 'Ethernet0/0/']],
+    base: 0,
+    vrp: 'Ethernet0/0/',
+    console: false,
+  },
   // PC and Server declare `interfacename="GE"` in the file but expose
   // `Ethernet0/0/1` on the CLI. eNSP's file vocabulary and VRP's differ here.
   PC: {
@@ -131,6 +154,60 @@ export const GEOMETRY = { editLeftOffset: 27, editTopOffset: 54 }
  */
 export const ICON = { w: 86, h: 86, left: -16.2, right: 70.2, top: -16.2, bottom: 70.2 }
 
+/**
+ * CLI namespace for one interface group.
+ *
+ * The eNSP file and VRP disagree in two places: PC/Server store `GE` but expose
+ * `Ethernet`, and firewalls store `GE` but number from `GigabitEthernet1/0/`.
+ * The model spec states those overrides by position; everything else follows from
+ * the declared interface name.
+ */
+function cliPrefixForGroup(sztype, enspPrefix, model, groupIndex) {
+  const override = MODEL_SPECS[model]?.groups?.[groupIndex]?.[4]
+  if (override) return override
+  if (enspPrefix === 'GE' || sztype === 'GE') return 'GigabitEthernet0/0/'
+  if (sztype === 'Serial' || enspPrefix === 'Serial') return 'Serial0/0/'
+  return 'Ethernet0/0/'
+}
+
+/**
+ * Build a port list from a device's own `<interface>` declarations.
+ *
+ * This matters for labs that add hardware: a stock AR2220 has no serial ports, but
+ * a NAT lab in the ICVE corpus mounts a serial card, so flat index 3 is
+ * `Serial0/0/0` there and `GigabitEthernet0/0/3` on a stock unit. The file states
+ * the real layout, so the file wins over the model table.
+ *
+ * @param {Array<{sztype: string, name: string, count: number, firstNumber: number|null}>} declarations
+ * @param {string} model
+ * @returns {string[]} CLI port name per flat index, in declaration order
+ */
+export function portsFromDeclarations(declarations, model) {
+  if (!declarations?.length) return []
+  const base = MODEL_SPECS[model]?.base ?? 0
+  const ports = []
+  declarations.forEach((d, groupIndex) => {
+    const first = d.firstNumber ?? base
+    const cli = cliPrefixForGroup(d.sztype, d.name, model, groupIndex)
+    for (let i = 0; i < d.count; i += 1) ports.push(`${cli}${first + i}`)
+  })
+  return ports
+}
+
+/**
+ * Resident interface declarations of a model, as `{sztype, name, count, firstNumber}`.
+ *
+ * Callers use this when they need to emit the `<interface>` block for a device.
+ */
+export function declarationsFor(model) {
+  return (MODEL_SPECS[model]?.groups ?? []).map(([sztype, name, count, firstNumber]) => ({
+    sztype,
+    name,
+    count,
+    firstNumber: firstNumber ?? null,
+  }))
+}
+
 /** Total declared interface count for a model. */
 export function portCount(model) {
   const spec = MODEL_SPECS[model]

package/src/core/topology.mjs

@@ -23,7 +23,14 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 
-import { MODEL_SPECS, GEOMETRY, portCount, flatIndexToVrp, vrpToFlatIndex } from './models.mjs'
+import {
+  MODEL_SPECS,
+  GEOMETRY,
+  portCount,
+  portsFromDeclarations,
+  flatIndexToVrp,
+  vrpToFlatIndex,
+} from './models.mjs'
 
 /**
  * Icon bounding box, measured from every cable anchor in eNSP's own samples.
@@ -90,14 +97,30 @@ export function parseTopology(xml) {
   const version = attr(xml.match(/<topo[^>]*>/)?.[0] ?? '', 'version')
 
   const devices = []
+  const portsById = new Map()
   for (const m of xml.matchAll(/<dev\b([^>]*)>([\s\S]*?)<\/dev>/g)) {
     const head = m[1]
     const body = m[2]
     const model = attr(head, 'model')
-    const declared = [...body.matchAll(/<interface\b[^>]*count="(\d+)"/g)]
-      .reduce((sum, x) => sum + Number(x[1]), 0)
+    // The device's own <interface> block is the authoritative port layout: a lab
+    // can mount extra cards (a serial card on an AR2220, for instance), and then
+    // the flat indices no longer match the stock model table.
+    const declarations = [...body.matchAll(/<interface\b([^>]*)\/?>/g)].map((decl) => {
+      const tag = decl[1]
+      const firstNumber = attr(tag, 'firstnumber')
+      return {
+        sztype: attr(tag, 'sztype') ?? 'Ethernet',
+        name: attr(tag, 'interfacename') ?? 'GE',
+        count: Number(attr(tag, 'count') ?? 0),
+        firstNumber: firstNumber === null ? null : Number(firstNumber),
+      }
+    })
+    const declared = declarations.reduce((sum, x) => sum + x.count, 0)
+    const ports = portsFromDeclarations(declarations, model)
+    const id = attr(head, 'id')
+    if (id) portsById.set(id, ports)
     devices.push({
-      id: attr(head, 'id'),
+      id,
       name: attr(head, 'name'),
       model,
       comPort: Number(attr(head, 'com_port') ?? 0) || null,
@@ -128,8 +151,8 @@ export function parseTopology(xml) {
       media: attr(pair, 'lineName') ?? 'Copper',
       srcName: src?.name ?? null,
       dstName: dst?.name ?? null,
-      srcPort: src ? interfaceName(src.model, srcIndex) : null,
-      dstPort: dst ? interfaceName(dst.model, dstIndex) : null,
+      srcPort: src ? (portsById.get(srcId)?.[srcIndex] ?? interfaceName(src.model, srcIndex)) : null,
+      dstPort: dst ? (portsById.get(dstId)?.[dstIndex] ?? interfaceName(dst.model, dstIndex)) : null,
     })
   }