@tikoci/centrs 0.1.3 → 0.1.4

package/commands/execute/README.md

@@ -16,11 +16,17 @@ 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): `:put [:parse
-  "<cmd>"]` is a **syntax** gate only — it does not catch unknown attributes or
-  bad values. Semantic validation needs `/console/inspect` or the server's own
-  re-validation on the write round-trip. A clean parse is necessary, not
-  sufficient.
+- Validation is two-stage (see constitution: validation; 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.
+  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.
 - centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` +
   `isWriteShaped` in `src/execute.ts`): it decides which validation runs and
   whether the write-confirm prompt fires. The shared `rosetta`/`lsp-routeros-ts`
@@ -102,30 +108,31 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 
 ## Flags
 
-| Flag                            | Behavior                                                                              |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → execute](../../docs/CLI.md#execute); this file does not
+duplicate that table. Behavior notes the generated reference cannot carry:
+
+- `--validate` is transport-appropriate but now one gate on every transport —
+  a single `:put [:parse ...]` that is read as a value (GH#230): REST/native
+  read the `ret` text (HTTP 200 / `as-string`); mac-telnet and ssh read the
+  console's printed value.
+- `--format` defaults to `text`; `CENTRS_FORMAT` sets the default.
+- `--quickchr` resolves host/port/auth from the live `@tikoci/quickchr`
+  (0.4.5+, optional dependency) descriptor, bypassing CDB/env resolution for
+  those fields.
+- `--` — use it when the command contains tokens that would otherwise be
+  claimed as centrs flags; otherwise the command must be quoted as a single
+  argument. In fan-out, positional targets come BEFORE `--` and the command
+  AFTER it (see **Target selection**).
+
+### Designed, not implemented
+
+Spec-tier flags with no implementation yet — today they fail as unknown flags:
+
+| Flag                            | Designed behavior                                                                      |
 | ------------------------------- | ------------------------------------------------------------------------------------- |
-| `--via <protocol>`              | Pin the transport (`native-api`, `rest-api`, `ssh`, or `mac-telnet`). No silent downgrade. A bare MAC target defaults to `mac-telnet`. |
-| `--host <host\|url>`            | Override the resolved host or base URL for the target.                                 |
-| `--port <n>`                    | Override the resolved management port.                                                 |
-| `--username` (alias `--user`, `-u`) / `--password` | RouterOS credentials; fall back to `CENTRS_USERNAME` / `CENTRS_PASSWORD`.              |
-| `--ssh-key <path>`              | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the ssh-agent. |
-| `--insecure`                    | Accept a new SSH host key (`--via ssh`) or a self-signed `api-ssl` TLS cert. Default verifies. |
-| `--cdb-file` / `--cdb-password` | Read target credentials from (and decrypt) a WinBox CDB file.                          |
-| `--resolve <none\|arp>`         | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`.          |
-| `--timeout <duration>`          | Per-request timeout. REST: ≤ 60s; other transports may allow longer.                  |
-| `--validate[=false]`            | Run transport-appropriate preflight validation before execution (default `true`): REST/native use `:parse` + `/console/inspect`; mac-telnet and ssh use a single console `:parse` (covers syntax + unknown-attribute). |
 | `--strict`                      | Treat any warning on a successful run as an error (`ok: false`, nonzero exit), like `-Werror`. Default is lenient (`ok: true` + `warnings`). |
-| `--yes`                         | Confirm write-shaped add/set/remove commands in non-interactive runs.                  |
-| `--max-bytes <n>`               | Byte budget for the rendered envelope; excess output is truncated with a warning + `meta.truncated` (not an error), matching `retrieve`. (Renamed from `--max-results`.) |
-| `--format <text\|json\|yaml>`   | Output format (alias `--json`). Defaults to `text`; `CENTRS_FORMAT` sets the default.  |
-| `--group <name>`                | Run across every CDB record in WinBox group `<name>`. Repeatable, combinable with `<target>` positionals plus `--where`/`--all`/`--default`; de-duped by record index. See **Target selection**. |
-| `--where <attr>=<value>`        | Device-class selector — run across every CDB record whose stored fact/comment-kv matches (e.g. `--where board=RB5009 /system/package/check-for-updates`). Repeatable (AND). See constitution: target selection. |
-| `--all`                         | Run across every CDB record (excludes the reserved `__default__`). See **Target selection**. |
-| `--default`                     | Select the reserved `__default__` record. See **Target selection**. |
-| `--near <lat>,<lon>,<radius>`   | Geo selector — run across CDB records whose GPS is within the great-circle radius (units `m`/`km`/`mi`/`ft`; bare = km). Lat-first. Union predicate; geo-less devices never match. See **Target selection**. |
-| `--bbox <south>,<west>,<north>,<east>` | Geo selector — run across CDB records whose GPS is inside the lat-first bounding box. Union predicate. See **Target selection**. |
-| `--concurrency <n>`             | Max in-flight targets during fan-out (integer ≥ 1). Transport-aware default: `rest-api` 8, others 4. |
-| `--`                            | End-of-options marker. Every token after `--` is taken as the literal RouterOS command, even flag-shaped ones — e.g. `centrs execute $R -- /interface print where disabled=yes`. In fan-out, positional targets come BEFORE `--` and the command AFTER it (`centrs execute r1 r2 -- /system/reboot`). Use it when the command contains tokens that would otherwise be claimed as centrs flags; otherwise the command must be quoted as a single argument. |
+| `--max-bytes <n>`               | Byte budget for the rendered envelope; excess output is truncated with a warning + `meta.truncated` (not an error), matching `retrieve`. (Will replace the implemented `--max-results`, which fails instead of truncating.) |
 
 ## SSH key selection
 
@@ -174,6 +181,11 @@ many tokens):
 - `execute r1 /system/resource/print` — a single positional target with no
   selector stays **single-target** (legacy split: first positional is the target,
   the rest is the command), never `FanoutData`.
+- `execute --quickchr lab /system/resource/print` — the quickchr
+  named-live-provider claims the target slots like a selector (positionals are
+  the command; no `--` needed). One `--quickchr` stays single-target; repeating
+  it fans out; mixing it with positionals or CDB selectors is
+  `usage/conflicting-flags` (constitution: resolution providers).
 
 Because `execute` is the primary **write** path, a write-shaped fan-out
 (add/set/remove) is gated by **`--yes`**, confirmed **once** up front; without it
@@ -213,7 +225,7 @@ How it is wired:
   `transport/capability-unsupported` (mac-telnet is execute/terminal only).
 - **Validation is one console `:parse`.** Over the console, `:put [:parse "<cmd>"]`
   prints both `syntax error` and `bad parameter <name>`, so a single gate covers
-  syntax **and** the unknown-attribute (semantic) check — no `/console/inspect`
+  syntax **and** the unknown-attribute (name-level) check — no `/console/inspect`
   table parsing. Maps to `validation/syntax` / `validation/unknown-attribute`,
   same codes as REST/native (see `docs/CONSTITUTION.md`, validation).
 - **Auth (grounded):** MTWEI is required; a stock device offers a 16-byte MD5 salt
@@ -243,7 +255,7 @@ Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
   **decided:** `--strict` promotes any warning on an otherwise-successful run to
   `ok: false` (nonzero exit), like `-Werror`; the default stays lenient
   (`ok: true` with the warning in the `warnings` channel). Tracked code
-  follow-up; the flag is in the table above.
+  follow-up; the flag is under **Designed, not implemented** above.
 
 These are deferred refinements to the already-grounded single-shot envelope,
 not blockers for the `rest-api`/`native-api` cells.

package/commands/execute/examples.md

@@ -62,14 +62,16 @@ The command is a script-shaped console expression, not a slash path plus verb,
 so REST must use the `/rest/execute` fallback.
 
 ```bash
-centrs execute $R ':put [/system/identity/get name]' --via rest-api --username $U --password $P
+centrs execute $R ':local a true; :if ($a = true) do={:put [/system/identity/get name]}' --via rest-api --username $U --password $P
 ```
 
 Envelope: `ok: true`, `data` is string-shaped (`data.output` or `data.ret`) and
 contains the CHR identity name, `meta.via=rest-api`, and
 `meta.validation.syntax=true`. `meta.validation.semantic` is absent or marked
 `not-applicable` because `/console/inspect` validates path-shaped commands, not
-arbitrary script expressions.
+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 ...]`
 
@@ -95,7 +97,7 @@ centrs execute $R '/ip/address/add address=198.51.100.11/32 interface=ether1 no-
 ```
 
 Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
-`error.cause.attribute="no-such-arg"` (or equivalent structured field),
+`error.context.parameter="no-such-arg"`,
 `meta.validation.syntax=true`, `meta.validation.source=/console/inspect`, and
 no address is added. This example is the product claim: syntax validation and
 semantic validation are separate gates.
@@ -435,3 +437,39 @@ Envelope: `meta.via=mac-telnet` when `$MAC` is not resolved from CDB and no
 `--host`/`--port`). If the caller wants IP-level REST or native API execution,
 they must opt into MAC-to-IP resolution (`--resolve arp` + `--via …`) before
 protocol selection.
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth
+come from the live descriptor — the CDB, `CENTRS_HOST`-style env, and the
+`__default__` ladder are bypassed for those fields. Covered by
+`test/integration/quickchr-target.test.ts`.
+
+### Q1. Run a command on a quickchr target (native API default)
+
+```bash
+centrs execute --quickchr $NAME ':put [/system/identity/get name]' --json
+```
+
+Envelope: `ok: true`, `meta.via=native-api` (execute's normal default),
+`meta.target.source.kind=provider`, `meta.target.identity=$NAME`.
+
+### Q2. A `--via` the descriptor does not forward → `quickchr/unsupported-via`
+
+```bash
+centrs execute --quickchr $NAME ':put 1' --via mac-telnet --json
+```
+
+Envelope: `ok: false`, `error.code=quickchr/unsupported-via` — quickchr v1
+forwards `rest-api`/`native-api`/`ssh` only; centrs never falls back to another
+transport.
+
+### Q3. Repeated `--quickchr` fans out; an unknown machine is an inner failure
+
+```bash
+centrs execute --quickchr $NAME --quickchr no-such-machine -- ':put 1' --json
+```
+
+Envelope: outer `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`;
+the unknown machine's inner error is `quickchr/machine-not-found`. Exit code 2
+(partial).