@tikoci/centrs 0.1.4 → 0.1.6

package/commands/execute/README.md

@@ -16,14 +16,23 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 - Mirror RouterOS `execute` semantics. Input is a CLI string; output is
   console-shaped text (or structured records for path+verb writes) wrapped in
   the standard envelope. This includes write-shaped add/set/remove.
-- Validation is two-stage (see constitution: validation; grounded on CHR 7.23.3,
+- Validation runs **offline first, then on the device** (see constitution:
+  validation; GH#354). Stage 1 is the corpus-gated analyzer over the exact
+  command string, with no connection: a syntax fault is rejected with a byte
+  span in `error.context.span` and the adapter is never dialed, and
+  `meta.validation.stages[]` then shows the device stage `skipped`. Stage 1
+  cannot see an unknown attribute — it has no per-menu schema — so stage 2 is
+  not optional.
+- Stage 2 is itself two gates (grounded on CHR 7.23.3,
   GH#230): a single `:put [:parse "<cmd>"]` covers both the syntax and the
   unknown-attribute (name-level) gate on **every** transport — `:parse` never
   throws; its return value's printed form (`(evl …)` / `(evl bad parameter …)` /
   `(<%% bad command name …)`) is read from the REST/native `ret` *and* the
   console output. That check is necessary, not sufficient: value-type errors pass
-  it, and the `/console/inspect` / server re-validation semantic checks are
-  separate.
+  it, and the `/console/inspect request=child` / server re-validation semantic
+  checks are separate. Command-level `request=completion` is deliberately not
+  used: it hangs REST and closes native API on RouterOS 7.12.2 (GH#343), while
+  `child` returns the complete argument-name set immediately.
   The outer RouterOS string literal escapes backslash, quote, and dollar so
   validation parses the caller's exact command rather than expanding variables
   in the wrapper.
@@ -73,13 +82,33 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   terminal width, so each transport handles width differently. **mac-telnet** is
   the only one that negotiates a size: `src/protocols/mac-telnet-console.ts`
   answers the device's terminal-size probe with a deliberately tall/wide screen,
-  so captured columns are neither wrapped nor paginated. **SSH execute** runs
-  *without* a pseudo-tty (`src/protocols/ssh.ts`), so RouterOS emits no
-  terminal-wrapped output to begin with — there is nothing to negotiate.
-  **REST/native-api** are not consoles, so terminal width never applies (they
-  return structured records, or a string `ret` for script-mode). There is
-  therefore no per-call `--width` knob today — an explicit width override is
-  deferred until a concrete need appears.
+  so captured columns are neither paginated nor wrapped *at the negotiated
+  width*. **SSH execute** runs *without* a pseudo-tty (`src/protocols/ssh.ts`),
+  so no width is negotiated at all. **REST/native-api** are not consoles, so a
+  terminal width never applies (they return structured records, or a string
+  `ret` for script-mode). There is therefore no per-call `--width` knob today —
+  an explicit width override is deferred until a concrete need appears.
+- **A device-side wrap that no width negotiation reaches (GH#352).** Declaring a
+  width is not sufficient, because RouterOS can wrap for reasons that are not
+  about width. On 7.23.6 / 7.24.3 / 7.25beta4 a settings menu with exactly one
+  property prints its value **one character per line**: `/system/identity/print`
+  returns `name: C` / `H` / `R` where 7.24.2 returns `name: CHR`. Measured on
+  stock CHR, the wrap is identical over REST `POST /rest/execute`, over
+  `ssh user@host "<cmd>"`, and over the mac-telnet console — including the
+  mac-telnet reader that has already answered the size probe with 512 columns,
+  and the ssh client that negotiates nothing. The console login modifiers
+  (`+c512w200h`, `+ct`, `+e`) do not change it, and it is not proportional to
+  the value's length. Every multi-property `print` is unaffected on the same
+  build, as is `:put [/system/identity/get name]`.
+
+  Consequence for this command: `data.ret` carries the device's console text
+  **verbatim**, wrap included — centrs cannot tell a layout newline from
+  content, and inventing a de-wrapper would corrupt legitimate output. Callers
+  that need a value rather than a rendering should read it structurally
+  (`retrieve`, or `api`) or ask the device for the scalar
+  (`:put [<menu>/get <property>]`). The integration examples compare identities
+  with `print` column wrapping collapsed for this reason — see
+  `collapsePrintWrapping` in `test/integration/chr.ts`.
 - Attribute values pass through **verbatim** — centrs does not guess types or
   coerce them (RouterOS REST tolerates string values; the native API is
   all-strings). Unlike `jo`-style KV builders, there is no per-value

package/commands/execute/examples.md

@@ -73,7 +73,7 @@ arbitrary script expressions. The `$a` variable must survive the validation
 wrapper: if that outer string expands it before `:parse`, this example fails even
 though RouterOS accepts the original command.
 
-### 5. Syntax reject from `:put [:parse ...]`
+### 5. Syntax reject before the write round-trip
 
 Malformed CLI is rejected by the syntax gate before semantic validation or the
 write round-trip.
@@ -82,9 +82,16 @@ write round-trip.
 centrs execute $R '/ip/address/add address="unterminated interface=ether1' --via rest-api --username $U --password $P --yes
 ```
 
-Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
-the RouterOS parse error string from `:put [:parse ...]`, `meta.via=rest-api`,
-and no address is added.
+Envelope: `ok: false`, `error.code=validation/syntax`, `meta.via=rest-api`, and
+no address is added.
+
+**Which stage rejects it changed in GH#354.** This input is now caught by the
+*offline* stage, so `error.context.validationStage="offline"`,
+`error.cause="explain/canonicalizer/unterminated-string"`,
+`error.context.span={"start":24,"end":54}`, and the device is never contacted —
+see V1–V3 below. It reached `:put [:parse ...]` before that. The code, the
+`meta.via`, and the no-mutation guarantee are unchanged, which is why the
+assertion in `test/integration/execute.test.ts` still reads `validation/syntax`.
 
 ### 6. Semantic reject that `:parse` accepts
 
@@ -202,14 +209,16 @@ centrs execute $A "/ip/address/remove numbers=$ID" --via native-api --port $API_
 Envelope: `ok: true`, `meta.via=native-api`. A subsequent retrieve of
 `/ip/address` does not contain `$ID`.
 
-### 15. Native syntax reject from `:parse`
+### 15. Native syntax reject
 
 ```bash
 centrs execute $A '/ip/address/add address="unterminated interface=ether1' --via native-api --port $API_PORT --username $U --password $P --yes
 ```
 
-Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
-the RouterOS parse error string, `meta.via=native-api`, and no address is added.
+Envelope: `ok: false`, `error.code=validation/syntax`, `meta.via=native-api`, and
+no address is added. The native twin of example 5, and it moved the same way:
+the offline stage rejects this input now, so the verdict no longer depends on
+the transport at all.
 
 ### 16. Native semantic reject after clean parse
 
@@ -285,6 +294,10 @@ Envelope: `ok: true`, `meta.via=mac-telnet`, `data.ret` is the console output an
 contains the device identity (cross-checked against REST). `meta.validation.source`
 is `:put [:parse ...] over mac-telnet`.
 
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
+
 ### 21. Write (add) over mac-telnet
 
 ```bash
@@ -329,6 +342,10 @@ Envelope: `ok: true`, `meta.via=ssh`, `data.ret` is the cleaned console output a
 contains the device identity (cross-checked against REST). `meta.validation.source`
 is `:put [:parse ...] over ssh`.
 
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
+
 ### S2. Multi-line read returns cleaned, column-aligned output
 
 ```bash
@@ -356,6 +373,61 @@ centrs execute 127.0.0.1 '/ip/address/add address=198.51.100.51/32 interface=eth
 Envelope: `ok: false`, `error.code=validation/unknown-attribute`, `meta.via=ssh`,
 and no address is added — the console `:parse` gate catches `bogus` pre-mutation.
 
+## Offline gate (stage 1)
+
+Validation runs offline before it runs on the device
+([`docs/CONSTITUTION.md` → Validation is the product](../../docs/CONSTITUTION.md#validation-is-the-product),
+GH#354). These two prove the stage exists and that a stage-1 rejection reaches no
+router. Run by `test/integration/execute.test.ts`.
+
+### V1. Offline reject, with the device stage never asked
+
+`:put [` is an unclosed bracket. The old local quote preflight counted quotes
+only, so this used to cost a full round trip to be told no; the analyzer rejects
+it with a byte span before anything is dialed.
+
+```bash
+centrs execute $R ':put [' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"`,
+`error.context.span={"start":5,"end":6}`,
+`error.context.diagnostics[0].code="explain/canonicalizer/unclosed"`,
+`error.position` absent (the offline byte offset is never dressed up as a
+RouterOS-reported one), `meta.validation.source` is the offline analyzer, and
+`meta.validation.stages` is `offline: failed` followed by `device: skipped`.
+
+### V2. The same rejection with no reachable router at all
+
+The proof that stage 1 opens no connection: point the same command at a port
+nothing is listening on. A gate that dialed first would report a
+`transport/*` error or hang until the timeout.
+
+```bash
+centrs execute 127.0.0.1:1 ':put [' --via rest-api --username $U --password $P --json
+```
+
+Envelope: identical to V1 — `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"` — and **not** a `transport/*` code.
+
+### V3. `--validate=false` disables the offline stage too
+
+One flag, one meaning. The escape hatch has to reach stage 1, or a caller hitting
+an analyzer defect would have no way past it. RouterOS then rejects the command
+itself on the run.
+
+```bash
+centrs execute $R ':put [' --via rest-api --username $U --password $P --json --validate=false
+```
+
+Envelope: `ok: false`, `error.code=routeros/request-failed` with RouterOS's own
+`syntax error (line 1 column 7)` in the summary — the **device** rejecting it, not
+centrs — plus `meta.validation.enabled=false`, `meta.validation.result="skipped"`,
+and `meta.validation.stages` listing **both** stages as `skipped`. A gated
+surface always reports every stage, so a consumer reading `stages` never has to
+special-case the disabled shape.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar