@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/docs/errors/cdb/create-failed.md

@@ -0,0 +1,20 @@
+# `cdb/create-failed`
+
+A new CDB file could not be created at the resolved location.
+
+`centrs devices init` creates an empty CDB at the path from `--cdb-file`,
+`CENTRS_CDB_FILE`, or the default `~/.config/tikoci/winbox.cdb`, making any
+missing parent directories. This error means the filesystem refused: typically
+a directory on the path is not writable by the current user, or a path
+component is a file rather than a directory. The underlying filesystem error
+(for example `EACCES`) is preserved as the error's `cause`; run
+with `--json` to see it.
+
+Nothing is written when this fails.
+
+## Fix
+
+- Check the permissions of the directories on the path shown in the error.
+- Or choose a writable location:
+  `centrs devices init --cdb-file PATH`, then pass the same `--cdb-file PATH`
+  (or set `CENTRS_CDB_FILE`) on later commands.

package/docs/errors/cdb/file-exists.md

@@ -0,0 +1,23 @@
+# `cdb/file-exists`
+
+`devices init` found a CDB already at the resolved location and wrote nothing.
+
+This is a warning on a successful result, not an error. Like `git init`,
+`centrs devices init` never overwrites an existing CDB. When the file there
+already loads as a CDB, `init` succeeds with `data.created: false` and
+`data.recordCount` set to the number of records it holds, and leaves the file
+byte-for-byte untouched. A bootstrap script can therefore run `init`
+unconditionally.
+
+A file at that path that does not load as a CDB is not reported here. `init`
+fails with the load error instead (`cdb/parse-failed`, or
+`cdb/password-required` for an encrypted CDB without `--cdb-password`), and
+still leaves the file alone.
+
+## Fix
+
+Usually nothing: the CDB you asked for exists.
+
+- To see what it holds: `centrs devices list --cdb-file PATH`.
+- To start fresh, pick a different path (`centrs devices init --cdb-file
+  NEW_PATH`), or move the existing file aside yourself; centrs never deletes it.

package/docs/errors/input/invalid-query.md

@@ -0,0 +1,36 @@
+# `input/invalid-query`
+
+A `--query` expression does not parse as a `print where` condition.
+
+## When it happens
+
+`retrieve --query` and `api --query` take what you would write after
+`print where`: `name=ether1`, `mtu>=1500 and !dynamic`,
+`(type=ether or type=vlan)`. centrs parses it before anything is sent, then
+runs it on the router as an API query. The error's `context.offset` points at
+the problem in `context.query`.
+
+centrs also refuses spellings that RouterOS reads differently from how they
+look, or does not accept:
+
+- `!name=value` is `(!name)=value` to RouterOS, which matches by accident.
+  Write `!(name=value)` or `name!=value`.
+- `not` is not a RouterOS operator. Use `!`.
+- Conditions separated only by a space. Join them with `and` or `or`.
+- An unquoted `=` inside a value. RouterOS reads `comment=x=yes` as
+  `(comment=x)=yes`, and `comment=x!=y` matches nothing. Quote it:
+  `comment="x=yes"`.
+- A space after the operator (`comment= x`), which RouterOS rejects too.
+- A string escape RouterOS does not have, such as lowercase hex `\0a` (hex is
+  two uppercase digits; `\ff` is `\f` then `f`), or a hex byte above `\7F`,
+  which a UTF-8 query value cannot carry.
+
+A bare name (`disabled`, `comment`) means what it means after `where`: `yes`
+for a boolean and "is set" for anything else. Only the router knows which a
+property is, so with `--validate=false` a bare name fails here too.
+
+## Fix
+
+- Quote values that contain spaces: `comment="uplink a"`.
+- Close every `(` and `"`.
+- Write a boolean out as `disabled=yes` if validation is off.

package/docs/errors/input/invalid-target.md

@@ -2,8 +2,30 @@
 
 The target string is invalid for the requested operation.
 
+A command's `<router>` is looked up in the CDB first: its `target`, or an
+`identity=` / `mac=` / `ip=` comment lookup key. When nothing matches, centrs
+treats the string as a host. This error means it is not a valid host either,
+or it is a URL that carries a path. Common causes:
+
+- **`quickchr:NAME`**: there is no `quickchr:` target prefix. A quickchr VM is
+  selected with a flag: `--quickchr NAME`.
+- **A typo or stray characters**, such as spaces or an extra `:` (`a b`,
+  `bad:host:name`).
+- **A base URL with a path**, such as `http://192.0.2.1/rest`. The RouterOS
+  menu path is a separate argument.
+
+The rejected string is in the error's `context.target`.
+
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `input/invalid-target`.
+Pass one of the accepted target forms:
+
+| Form | Example |
+| ---- | ------- |
+| CDB target or lookup key | `edge1` (see `centrs devices list`) |
+| IP address or hostname, optional `:port` | `192.0.2.1`, `router.example:8080` |
+| Base URL without a path | `https://192.0.2.1:8443` |
+| quickchr VM | `--quickchr NAME` (a flag, not a prefix) |
+
+With an explicit `--cdb-file` and no `__default__` fallback record, a string
+that matches no record stops earlier with `cdb/not-found-target`.

package/docs/errors/input/local-destination.md

@@ -0,0 +1,20 @@
+# `input/local-destination`
+
+A local download destination cannot be written (missing parent directory, a directory, or no permission).
+
+`transfer download` checks the local destination before it reads anything
+from the device. The parent directory must already exist, because centrs does
+not create directories, and the destination itself must not be a directory.
+A path that cannot be checked at all (no permission on a directory along the
+way, a file used as a directory, a symlink loop) fails the same way. A write
+that still fails afterwards (no permission, the directory removed
+mid-transfer) reports this code too, with the operating-system error as the
+cause.
+
+## Fix
+
+- Create the parent directory first: `mkdir -p DIR`, then retry the download.
+- Name a file, not a directory: `download fw.rsc ./backups/fw.rsc`, not
+  `download fw.rsc ./backups/`.
+- Pass `-` as the local path to write the bytes to stdout instead.
+- For a fan-out download, `--out-dir` must be an existing directory.

package/docs/errors/input/unsupported-query.md

@@ -0,0 +1,19 @@
+# `input/unsupported-query`
+
+A `--query` uses something the RouterOS API query cannot run.
+
+## When it happens
+
+`--query` runs on the router as an API query (native `?` words, REST
+`.query`), and that query language has no regex (`~`), no prefix membership
+(`in`), and no script evaluation. A value starting with `$`, `[` or `{`, or a
+`$` inside a quoted value, would need RouterOS's script evaluator. centrs
+refuses these rather than filtering some other way and calling it a router
+filter.
+
+## Fix
+
+- Read the rows without that condition and filter them yourself.
+- Or run the console form, which returns console text rather than rows:
+  `centrs execute <router> '/ip/address/print where interface~"^ether"'`.
+- For a literal `$` in a quoted value, escape it as `\$`.

package/docs/errors/internal/byte-string.md

@@ -0,0 +1,13 @@
+# `internal/byte-string`
+
+A binary RouterOS word held a character that is not a byte.
+
+## Fix
+
+This is a centrs bug; report it with the command that triggered it.
+
+`transfer` moves `/file` contents over REST and native-api as byte strings,
+one string code unit per byte (#404). A code unit above U+00FF has no single
+byte, so centrs refuses the request before it reaches the router rather than
+silently keeping the low byte. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error contract.

package/docs/errors/routeros/invalid-value.md

@@ -1,12 +1,13 @@
 # `routeros/invalid-value`
 
-RouterOS rejected the value supplied for an argument. The offending argument
-name is captured in `context.argument`.
+RouterOS rejected a supplied value. When RouterOS names the offending argument,
+it is captured in `context.argument`.
 
 ## Typical RouterOS strings
 
 - `invalid value for argument <name>`
 - `invalid value of <name>`
+- `input does not match ...`
 
 ## Fix
 

package/docs/errors/settings/invalid-timeout.md

@@ -18,6 +18,12 @@ Like the other typed-value codes here, this isn't `settings`-exclusive:
 flag, so the same failure shape shows up anywhere a duration string is
 resolved, not just through `settings set`.
 
+`retrieve --sample <interval>` and `retrieve --follow --sweep <period>` are
+stricter: the value needs a unit (`5s`, `500ms`, `1m`). `--sample` must be
+above zero; `--sweep 0` is allowed and turns the sweep off. A bare `--sample 5` fails here
+because RouterOS reads `interval=5` as five seconds while centrs reads a bare
+number as milliseconds; pass the unit you mean.
+
 One write detail worth knowing: `settings set timeout` writes the
 **canonical parsed milliseconds**, not the raw suffixed string you typed —
 `centrs settings set timeout 5s` writes `CENTRS_TIMEOUT=5000` to

package/docs/errors/transport/cancel-unacknowledged.md

@@ -0,0 +1,24 @@
+# `transport/cancel-unacknowledged`
+
+RouterOS did not acknowledge a stream's /cancel within the timeout; centrs ended
+the stream and closed the session locally.
+
+## When it happens
+
+This is a **warning** on the summary envelope of `centrs api … --stream`, not a
+failure. The stream stopped for its normal reason (`--duration` elapsed, or
+Ctrl-C), and centrs sent RouterOS `/cancel` for the `/listen`. A cooperating
+router answers with an `interrupted` trap and `!done` within milliseconds. This
+one did not answer within `--timeout`, so centrs stopped waiting, closed the
+native API session and finished.
+
+The summary's `stopReason` is still the reason the stream stopped. The warning
+records that the router never confirmed the cancel, so the stop was local.
+
+## Fix
+
+- Usually nothing: the stream ended when you asked, and the session is closed.
+- If it repeats against one router, the API connection is likely stalled (a
+  router under load, or a firewall or NAT device holding the TCP session).
+  Check the router's CPU and the path to it before relying on long-lived
+  streams there.

package/docs/errors/transport/stream-overflow.md

@@ -0,0 +1,21 @@
+# `transport/stream-overflow`
+
+More stream replies were waiting unread than the buffer allows, so centrs ended
+the stream rather than drop any.
+
+## When it happens
+
+`centrs retrieve <router> <menu> --follow` buffers changes between RouterOS and
+the reader, up to 50,000. The buffer fills when the reader stops reading (a
+stalled pipe), or when a burst arrives while a long snapshot is still loading.
+centrs never drops a change silently, because the state you hold would then
+look current while being wrong. It ends the follow with this error instead, as
+the failed summary (`stopReason: "transport-error"`).
+
+## Fix
+
+- The state you built from the lines is stale. Follow again: the new follow
+  starts with a fresh snapshot.
+- Read lines as they arrive. Don't buffer the whole output before processing.
+- For a very busy menu, follow a narrower menu (for example `/interface/vlan`
+  instead of `/interface`).

package/docs/errors/usage/removed-flag.md

@@ -0,0 +1,20 @@
+# `usage/removed-flag`
+
+A flag or request field was removed; the error names its replacement.
+
+## Fix
+
+Run the replacement printed in the error's remediation.
+
+`api --listen` (and the library's `ApiRequest.listen`) is the current case
+(#402). It meant "stream the replies" and also turned a GET of a menu into a
+change subscription. `api` now sends the command as typed:
+
+- To follow changes, request the menu's `listen`:
+  `centrs api <router> ip/address/listen`. A `/listen` endpoint implies
+  `--stream` and native-api.
+- To stream any other command's replies, use `--stream`
+  (`ApiRequest.stream` / `apiStream()` in the library).
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract.

package/docs/errors/validation/menu-unavailable.md

@@ -0,0 +1,22 @@
+# `validation/menu-unavailable`
+
+RouterOS 7 publishes this menu or command, but this device does not have it —
+usually hardware, build or version.
+
+Same detection as
+[`validation/package-missing`](package-missing.md): RouterOS rejected a path
+segment, and centrs's path catalog knows the path. This code is used when the
+published gates are not a package alone — a hardware capability
+(`/interface/w60g` needs `60ghz`), a build condition, or no gate at all, which
+usually means the device's RouterOS version predates or dropped the menu.
+The path can end in a command rather than a menu: `/system/license/output` is
+published `nochr`, so a CHR rejects it here, and the summary calls it a command.
+
+`error.context` carries `path`, `segment`, `gates` (root-first, each with the
+`package`, `syscap` and `conditions` MikroTik published) and `detail`.
+
+## Fix
+
+The command is not the problem. Compare the gates with the device: installed
+packages (`/system/package/print`), model, and RouterOS version
+(`/system/resource/print`). Run the command only on devices that have the menu.

package/docs/errors/validation/not-followable.md

@@ -0,0 +1,23 @@
+# `validation/not-followable`
+
+The RouterOS menu cannot be followed: it is a single record, or its print has
+no follow-only.
+
+## When it happens
+
+`centrs retrieve <router> <menu> --follow` checks the menu live through
+`/console/inspect` before following it. RouterOS can follow a menu only when
+its `print` takes `follow-only`, which is the same thing native-API `listen`
+needs. Single-record menus such as `/system/resource`, `/system/identity` and
+`/ip/dns` never take it, and neither do some list menus.
+
+Nothing was followed. The error's `context.singleton` says which case it was.
+
+## Fix
+
+- Read the menu once: `centrs retrieve <router> <menu>`.
+- To see a value change over time, sample it:
+  `centrs retrieve <router> <menu> --sample 5s` (one line per complete read,
+  until `--count`, `--duration` or Ctrl-C).
+- If you expected the menu to be followable, check the path with
+  `centrs retrieve <router> <menu> --list-attributes`.

package/docs/errors/validation/package-missing.md

@@ -0,0 +1,29 @@
+# `validation/package-missing`
+
+This device has no such menu or command; MikroTik publishes it in a package
+that is likely not installed.
+
+RouterOS's `:parse` reports a menu it does not have as `syntax error` (slash
+spelling, `/zerotier/print`) or `bad command name` (space spelling,
+`/zerotier print`). Both point at the segment it could not resolve. centrs
+looks that path up in its path catalog — every RouterOS 7.10–7.25 build, all
+extra packages — and when MikroTik publishes it behind a package and nothing
+else, reports this code instead of `validation/syntax`.
+
+`error.context` carries:
+
+- `path` — the absent menu or command, from the root (`/zerotier`). The summary
+  says which, from the path catalog's kind. An abbreviated segment
+  is expanded when the catalog has one unique completion.
+- `segment` — the segment as written.
+- `packages` — the published package names. These are MikroTik's build names
+  and can differ from the installable package (`wireless-rep` ships in
+  `wireless`, `userman-5` in `user-manager`).
+- `gates` — every published gate on the path, root-first.
+- `detail` — RouterOS's own words; `error.position` is its byte column.
+
+## Fix
+
+The command is not the problem. Check the installed packages with
+`/system/package/print`, install the package and reboot, or run the command only
+on devices that have it.

package/docs/errors/validation/unknown-path.md

@@ -1,9 +1,21 @@
 # `validation/unknown-path`
 
-The RouterOS path does not expose the requested command.
+The RouterOS path does not exist, or does not expose the requested command.
+
+Two sources raise it:
+
+- **`execute` / `validate`** — RouterOS's `:parse` rejected a path segment, and
+  the path is in no published RouterOS 7 build centrs knows of (its path
+  catalog covers 7.10–7.25, all extra packages). Usually a typo.
+  `error.context.path` is the path through the rejected segment,
+  `error.context.segment` the segment as written, and `error.position`
+  RouterOS's byte column. A path the catalog does know is reported as
+  [`validation/package-missing`](package-missing.md) or
+  [`validation/menu-unavailable`](menu-unavailable.md) instead.
+- **`retrieve` / `api`** — `/console/inspect` shows the path has no command of
+  the kind requested (no `print` or `get` to read with).
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `validation/unknown-path`.
+Check the spelling of the segment in `error.context.segment`. `centrs explain
+'<command>'` shows how the rest of the command reads offline.

package/docs/errors/wait/deadline-exceeded.md

@@ -0,0 +1,14 @@
+# `wait/deadline-exceeded`
+
+The wait deadline passed before readiness or its condition was established.
+
+## Fix
+
+Check the predicate and the router's current state, then choose a longer
+`--wait` if the operation legitimately needs more time. `--timeout` bounds
+individual requests and does not extend the overall deadline.
+
+`meta.operation.wait` reports `deadline-elapsed`, elapsed milliseconds,
+attempts and completed observations. A failed or unfinished read never proves
+an empty result. If the last attempt failed with a transient transport error,
+that error is preserved instead of this code.

package/docs/errors/wait/interrupted.md

@@ -0,0 +1,10 @@
+# `wait/interrupted`
+
+The wait was cancelled before readiness or its condition was established.
+
+## Fix
+
+Run the wait again when you want to continue. Ctrl-C or an aborted library
+signal is a failure to establish the condition, even if some reads completed.
+The final envelope reports `meta.operation.wait.stopReason: "interrupted"`
+and the partial attempts and observations.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.6",
+	"version": "0.1.8-next.0",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -12,18 +12,18 @@
 	"packageManager": "bun@1.3.14",
 	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.5.7",
-		"@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
-		"@types/bun": "^1.3.13",
+		"@biomejs/biome": "2.5.15",
+		"@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
+		"@types/bun": "1.3.14",
 		"cloc": "^2.6.0-cloc",
-		"cspell": "^10.0.0",
+		"cspell": "^10.3.6",
 		"has-flag": "4.0.0",
-		"markdownlint-cli2": "^0.23.0",
-		"secretlint": "^13.0.2",
-		"typedoc": "^0.28.19"
+		"markdownlint-cli2": "^0.23.3",
+		"secretlint": "^13.0.7",
+		"typedoc": "^0.28.20"
 	},
 	"optionalDependencies": {
-		"@tikoci/quickchr": "^0.4.7"
+		"@tikoci/quickchr": "^0.4.8"
 	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
@@ -133,10 +133,13 @@
 		"explain:token-census:readme:check": "bun run scripts/explain-token-census.ts --readme --check",
 		"security": "bun run lint:secretlint && bun run lint:markdownlint"
 	},
+	"overrides": {
+		"smol-toml": "^1.9.1"
+	},
 	"type": "module",
 	"types": "src/index.ts",
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"zod": "^4.4.3"
+		"@modelcontextprotocol/sdk": "^1.32.1",
+		"zod": "^4.6.7"
 	}
 }