From 84fa38b41f2e19264f77953e749ea3071cba45ce Mon Sep 17 00:00:00 2001 From: Dov Benyomin Sohacheski Date: Wed, 3 Jun 2026 02:42:54 +0300 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Rename=20ipc-server=20to=20w?= =?UTF-8?q?s-extension=20in=20source=20tree=20[skip=20ci]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contribute/contribution-workflow.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contribute/contribution-workflow.md b/docs/contribute/contribution-workflow.md index f92cf64..338247d 100644 --- a/docs/contribute/contribution-workflow.md +++ b/docs/contribute/contribution-workflow.md @@ -159,10 +159,10 @@ The trees below displays the main files and folders and their intended use. ├── .gitignore # Files to not track in `git` ├── renovate.json # Track dependency versions ├── src # The main directory for image assets and build steps -│ ├── build # Helper scripts and dependency definitions -│ ├── home # Directory mapped to `~` in the container -│ ├── ipc-server # IPC server extension for Kloud Workspace -│ └── rootfs # Directory mapped to `/` in the container +│ ├── build # Helper scripts and dependency definitions +│ ├── home # Directory mapped to `~` in the container +│ ├── rootfs # Directory mapped to `/` in the container +│ └── ws-extension # Integration extension for Kloud Workspace └── tests # Test bench ├── browser # Browser tests using playwright ├── helpers # Fixtures, consts, utilities, and test bootstrapping From d8ca397d1e286e5fe138733ce73c81ef691f24a0 Mon Sep 17 00:00:00 2001 From: Dov Benyomin Sohacheski Date: Sun, 7 Jun 2026 11:31:04 +0300 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20Document=20`show=20env`=20do?= =?UTF-8?q?tted=20query=20keys,=20WS=5F*=20as=20binding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `ws-cli show env` is queried by the canonical dotted key (`server.port`); the matching `WS_*` variable is the binding operators export, not a query key (a `WS_*` positional exits 2 with a hint). Update the `env` command reference and the configuration-source tip accordingly. --- docs/settings/configuration.md | 6 ++++-- docs/tools/ws-cli.md | 28 +++++++++++++++++++--------- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/docs/settings/configuration.md b/docs/settings/configuration.md index 464dbd6..4b4edf7 100644 --- a/docs/settings/configuration.md +++ b/docs/settings/configuration.md @@ -90,8 +90,10 @@ containers: ::: ::: tip -`ws-cli show env ` reports where the value came from: `env-set`, `env-file`, -`secret-file-default`, or `yaml-default`. +`ws-cli show env ` (e.g. `ws-cli show env server.port`) reports where the +value came from: `env-set`, `env-file`, `secret-file-default`, or `yaml-default`. +Query the dotted key — the matching `WS_*` variable (e.g. `WS_SERVER_PORT`) is what you +`export` to set it. ::: diff --git a/docs/tools/ws-cli.md b/docs/tools/ws-cli.md index f65e268..b1d70ed 100644 --- a/docs/tools/ws-cli.md +++ b/docs/tools/ws-cli.md @@ -131,19 +131,29 @@ Serve internal assets. Display information about the current workspace instance. -- **`env `:** Display the resolved value of a `WS_*` environment variable. Falls back to the default - declared in `env.reference.yaml` when unset. - - *(no flags)* — pretty mode: shows the key, schema description, markdown-rendered `longDescription`, - resolved value, and source label (`env-set` / `deprecated-alias` / `yaml-default`). - - `--value` — print the resolved value as a single line (script-friendly). +- **`env `:** Display the resolved value of a setting, queried by its canonical **dotted** key + (e.g. `ws-cli show env server.port`). Falls back to the default declared in `env.reference.yaml` when unset. + The matching `WS_*` variable (`WS_SERVER_PORT`) is the environment binding you `export` to set it — it is + not a query key (`ws-cli show env WS_SERVER_PORT` exits `2` with a hint pointing at the dotted form). + - *(no flags)* — pretty mode: shows the dotted key (and its `WS_*` binding), schema description, + markdown-rendered `longDescription`, resolved value, and source label (`env-set` / `deprecated-alias` / `yaml-default`). + - `--value` — print the resolved value as a single line (script-friendly). Combinable with `--check` + to emit the value only when the operator has set the variable (`--value --check`). - `--as bool|int|list` — validate and emit the resolved value as the requested type (`bool` exits `0` truthy / `1` falsy / error on garbage; `int` prints canonical int10; - `list` newline-splits using the YAML `delimiter:` or `--delimiter` override). Mutually exclusive with `--value` / `--check`. - - `--check [--deprecated ]` — existence probe. Exits `0` when the preferred variable is set; + `list` newline-splits using the YAML `delimiter:` or `--delimiter` override). Mutually exclusive with `--value`. + - `--check [--deprecated ]` — existence probe. `--deprecated` takes a **raw `WS_*` alias** (deprecated + aliases have no dotted form). Exits `0` when the preferred variable is set; `1` when unset (stderr carries a deprecation warning if `--deprecated` is supplied and the alias is set); `2` when both the preferred variable and the deprecated alias are set (aborts to stderr). - - Unknown keys (not declared in `env.reference.yaml`) exit non-zero with stderr - `Unknown env var []` in all non-`--check` modes. + - `--or-skip` — modifier on `--value` / `--value --check` / `--as bool`: exit `1` (not an error) on the + natural absence of the chosen projection, emitting a `Skipped: env [] not set` debug breadcrumb to + stderr. Lets a script guard with `if val=$(ws-cli show env --value --or-skip); then …`. + - `--validate ` — modifier on `--as list`: each token must full-match the anchored caller-supplied + charset; on any miss the whole list fails **closed** (no tokens emitted, exit `3`, stderr + `Rejected: invalid item []`). Centralizes token rejection for untrusted delimited sinks. + - Unknown dotted keys (not declared in `env.reference.yaml`) exit non-zero with stderr + `Unknown env var []` (echoing the typed dotted form) in all non-`--check` modes. - **`ip`:** - **`internal`:** Display the internal IP address. - **`node`:** Display the node/host IP address.