The index of commands the console can do was missing fifteen of them #1492

Merged
jaylouisw merged 1 commit from fix/help-index-complete into main 2026-11-12 06:06:32 +00:00
Owner

The symptom

help is the console's own index — the thing an operator types to find out what the box can do. Two features landed yesterday. I typed help on a 2811 and neither was there:

  ping <address|name> [<count 1-50>] [at <ms>]   IPv4 or IPv6; a name is resolved through the lab's DNS servers
  ...

No traceroute. No clock rate. Both are documented in docs/CLI.md, both are accepted at the console, both were unlisted in the one place a person in a lab actually looks.

Asking the parser instead of the documentation turned up more. Extracting every token the dispatcher compares against head in engine/cli.js — the console's whole vocabulary, in the console's own spelling — and diffing that against _help() gave 24 absent verbs, and the missing ones were not trivia:

accepted since not in help
#1484 traceroute, tracert
#1483 clock rate (and speed, duplex, description — never listed either)
the DHCP pool feature network, range, default-router, lease, host, excluded-address, dns-server — the index knew only no ip dhcp pool <name>
the SCION feature scion <isd-as>, no scion

So you could create a DHCP pool and the index never told you what to type inside it; you could clock a serial link and the index never mentioned the command; you could traceroute and the index had never heard of it. The forward direction — everything help advertises is accepted — was already a test. The direction that mattered had been left to memory.

What changed

The index gains the fourteen commands it was missing, in the same shape as their neighbours:

  traceroute|tracert <address|name> [max <n>]   each hop that answers, from its own time-exceeded
  speed auto|forced <mbps> | duplex half|full | description <text>   (interface mode)
  clock rate <bps>                       (interface mode, serial only) makes this end the DCE
  network <net> <mask> | range <a> <b> | default-router <gw> | lease <s>  (in a dhcp pool)
  host <address> <mac> | excluded-address|excluded address <a> [<b>] | dns-server <address...>  (in a dhcp pool)
  scion <isd-as> | no scion        the device SCION ISD-AS, e.g. 1-ff00:0:110  (config mode)

The duplicate ping row went too: the index had two, one of them the older and less complete.

test/help-completeness.test.js now checks the direction that used to be memory. It reads the dispatcher's vocabulary out of engine/cli.js — every head === '…' token — drops the keypresses (?, exit, quit, logout, end, help, and the abbreviations conf, en, int), and requires every remaining verb to be named in the index. Fifty tokens, forty-one requiring a line.

Evidence

test/help-completeness.test.js — 8 checks, 8 passed / 0 failed. With the old index and the new check: 5 passed / 3 failed, naming all fifteen missing verbs (clock, default-router, description, dns-server, duplex, excluded, excluded-address, host, lease, network, range, scion, speed, traceroute, tracert).

The opposite direction stays a hand-written list on purpose, and now carries fourteen new rows — each typed at a real device, each required to be accepted: traceroute, tracert, clock rate, no clock rate, speed, duplex, description, network, range, default-router, lease, host, excluded-address, dns-server. 98 advertised commands, all accepted.

Why a hand list there and a derived one here: the forward direction has to describe modes as well as words (['clock rate <bps>', 'iface', ROUTER]), and recovering modes from the index's prose would mean writing a prose parser. The reverse direction has no such problem — the parser's own tokens are the console's vocabulary — which is exactly why it is worth deriving, and why the gap survived two features.

Docs: docs/CLI.md, new section "help is an index, and a test reads it out of the parser", with the table of what was missing and why the two directions are checked differently.

Full suite: 243 suites, 9,042 assertions, 0 failed. Syntax 312 files.

## The symptom `help` is the console's own index — the thing an operator types to find out what the box can do. Two features landed yesterday. I typed `help` on a 2811 and neither was there: ``` ping <address|name> [<count 1-50>] [at <ms>] IPv4 or IPv6; a name is resolved through the lab's DNS servers ... ``` No `traceroute`. No `clock rate`. Both are documented in `docs/CLI.md`, both are accepted at the console, both were unlisted in the one place a person in a lab actually looks. Asking the parser instead of the documentation turned up more. Extracting every token the dispatcher compares against `head` in `engine/cli.js` — the console's whole vocabulary, in the console's own spelling — and diffing that against `_help()` gave **24 absent verbs**, and the missing ones were not trivia: | accepted since | not in `help` | |---|---| | #1484 | `traceroute`, `tracert` | | #1483 | `clock rate` (and `speed`, `duplex`, `description` — never listed either) | | the DHCP pool feature | `network`, `range`, `default-router`, `lease`, `host`, `excluded-address`, `dns-server` — the index knew only `no ip dhcp pool <name>` | | the SCION feature | `scion <isd-as>`, `no scion` | So you could create a DHCP pool and the index never told you what to type inside it; you could clock a serial link and the index never mentioned the command; you could traceroute and the index had never heard of it. The forward direction — *everything `help` advertises is accepted* — was already a test. The direction that mattered had been left to memory. ## What changed The index gains the fourteen commands it was missing, in the same shape as their neighbours: ``` traceroute|tracert <address|name> [max <n>] each hop that answers, from its own time-exceeded speed auto|forced <mbps> | duplex half|full | description <text> (interface mode) clock rate <bps> (interface mode, serial only) makes this end the DCE network <net> <mask> | range <a> <b> | default-router <gw> | lease <s> (in a dhcp pool) host <address> <mac> | excluded-address|excluded address <a> [<b>] | dns-server <address...> (in a dhcp pool) scion <isd-as> | no scion the device SCION ISD-AS, e.g. 1-ff00:0:110 (config mode) ``` The duplicate `ping` row went too: the index had two, one of them the older and less complete. `test/help-completeness.test.js` now checks the direction that used to be memory. It reads the dispatcher's vocabulary out of `engine/cli.js` — every `head === '…'` token — drops the keypresses (`?`, `exit`, `quit`, `logout`, `end`, `help`, and the abbreviations `conf`, `en`, `int`), and requires every remaining verb to be named in the index. Fifty tokens, forty-one requiring a line. ## Evidence `test/help-completeness.test.js` — **8 checks, 8 passed / 0 failed**. With the old index and the new check: **5 passed / 3 failed**, naming all fifteen missing verbs (`clock, default-router, description, dns-server, duplex, excluded, excluded-address, host, lease, network, range, scion, speed, traceroute, tracert`). The opposite direction stays a hand-written list on purpose, and now carries fourteen new rows — each typed at a real device, each required to be accepted: `traceroute`, `tracert`, `clock rate`, `no clock rate`, `speed`, `duplex`, `description`, `network`, `range`, `default-router`, `lease`, `host`, `excluded-address`, `dns-server`. 98 advertised commands, all accepted. Why a hand list there and a derived one here: the forward direction has to describe *modes* as well as words (`['clock rate <bps>', 'iface', ROUTER]`), and recovering modes from the index's prose would mean writing a prose parser. The reverse direction has no such problem — the parser's own tokens are the console's vocabulary — which is exactly why it is worth deriving, and why the gap survived two features. Docs: `docs/CLI.md`, new section "`help` is an index, and a test reads it out of the parser", with the table of what was missing and why the two directions are checked differently. Full suite: 243 suites, 9,042 assertions, 0 failed. Syntax 312 files.
The index of commands the console can do was missing fifteen of them
Some checks failed
CI / Classify the change (pull_request) Successful in 16s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 18) (pull_request) Failing after 26s
CI / Test (Node 20) (pull_request) Successful in 3m28s
CI / Test (Node 22) (pull_request) Successful in 3m6s
CI / Server smoke test (pull_request) Successful in 40s
CI / Docker build (pull_request) Successful in 56s
61bc1809d7
`help` is how an operator finds out what a box can do, so an accepted verb the index never mentions is a verb
only its author knows about. Extracting the dispatcher's whole vocabulary out of engine/cli.js - every
`head === '...'` token - and diffing it against `_help()` gave 24 absent, and the missing ones were not trivia
(#1491):

  traceroute, tracert        a whole feature (#1484), documented in docs/CLI.md, absent from help;
  clock rate                 the other whole feature (#1483); speed, duplex and description were never
                             listed either;
  network, range,             the whole DHCP pool sub-mode: the index knew only `no ip dhcp pool <name>`, so
  default-router, lease,      you could create a pool and never find out what to type inside it;
  host, excluded-address,
  dns-server
  scion / no scion           a whole addressing scheme.

  * engine/cli.js: the index gains those commands in the shape of their neighbours, and the duplicate `ping`
    row (the older, less complete one) goes;
  * test/help-completeness.test.js: the reverse direction is now derived from the parser instead of remembered
    - 50 tokens, the keypresses (?, exit, quit, logout, end, help, conf, en, int) dropped, and every remaining
    verb required to be named. The forward direction stays a hand list on purpose (it has to carry modes), and
    grows fourteen rows that are each typed at a real device: 98 advertised commands, all accepted.

Evidence: 8 checks, 8/0. Old index + new check: 5 passed / 3 failed, naming all fifteen
(clock, default-router, description, dns-server, duplex, excluded, excluded-address, host, lease, network,
range, scion, speed, traceroute, tracert).

Suite 243 suites, 9042 assertions, 0 failed. Syntax 312 files.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 06:03:39 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1492
No description provided.