yeelight-home 0.1.6 → 0.1.7

package/CONFIG.md

@@ -38,6 +38,8 @@ Supported region values:
 Examples:
 
 ```sh
+yeelight-home version --json
+yeelight-home doctor
 yeelight-home doctor --json
 yeelight-home doctor --json --region sg
 YEELIGHT_CLOUD_REGION=eu yeelight-home home list --json
@@ -50,6 +52,7 @@ Profiles let one machine keep separate local metadata for different accounts, ho
 ```sh
 yeelight-home profile list --json
 yeelight-home profile show --profile default --json
+yeelight-home profile show --profile family --region sg --house-id <house-id> --json
 yeelight-home profile use --profile family --region cn
 yeelight-home profile use --profile family --region cn --house-id <house-id>
 yeelight-home profile delete --profile family
@@ -78,21 +81,23 @@ yeelight-home auth login --qr --profile default --qr-png /tmp/yeelight-login.png
 
 ```sh
 yeelight-home auth token set --profile default --token <access-token> --region cn
+printf '%s' "$YEELIGHT_DEV_TOKEN" | yeelight-home auth token set --profile dev --region dev --stdin --json
 yeelight-home auth token set --profile default --token <access-token> --region cn --house-id <house-id>
 yeelight-home auth token delete --profile default
 ```
 
-Use token import only outside AI chat. Tokens are redacted from normal output and are not written to profile metadata.
+Use token import only outside AI chat. Prefer `--stdin` for real terminals so the token does not appear in shell history.
+Tokens are redacted from normal output and are not written to profile metadata.
 Token-only setup is valid. Omit `--house-id` when you only need account-level commands or will choose a default home later.
 
 ### Status
 
 ```sh
-yeelight-home auth status --json
+yeelight-home auth status
 yeelight-home auth status --json --profile family
 ```
 
-The status output includes token presence and source, not token values.
+The status output includes token presence and source, not token values. Use `--json` when an automation or support script needs structured output.
 
 ## Home Selection
 
@@ -110,6 +115,7 @@ The selected home is a default context, not an authentication requirement. Accou
 
 ```sh
 yeelight-home config get --json
+yeelight-home config list --profile family --json
 yeelight-home config set --profile family --region cn --house-id <house-id> --json
 yeelight-home config unset --profile family --house-id --json
 ```
@@ -149,7 +155,7 @@ Default paths are platform-specific:
 | Linux | `~/.yeelight-home` or XDG-compatible directories depending on environment |
 | Windows | `%LOCALAPPDATA%\YeelightHome` |
 
-Run `yeelight-home doctor --json` to see the exact paths on the current machine.
+Run `yeelight-home doctor` for a readable summary or `yeelight-home doctor --json` for the exact machine-readable paths on the current machine. Add `--online` only when you want to compare local install channels with public GitHub, npm, and Homebrew latest versions.
 
 ## Skill Integration
 
@@ -162,8 +168,11 @@ yeelight-home invoke --stdin
 Skill wrappers find the CLI in this order:
 
 1. `YEELIGHT_HOME_BIN`
-2. Development-only source checkout binary
-3. `yeelight-home` on `PATH`
+2. `yeelight-home` on `PATH`
+
+Published Skill packages do not carry or auto-discover Runtime source-tree
+binaries. Use `YEELIGHT_HOME_BIN` for a deliberate local override, or install
+the public CLI so it is available on `PATH`.
 
 After installation:
 
@@ -190,6 +199,12 @@ yeelight-home auth status --json
 yeelight-home auth login --qr
 ```
 
+If QR login is unavailable and you already have an approved token, import it locally outside chat:
+
+```sh
+printf '%s' "$YEELIGHT_TOKEN" | yeelight-home auth token set --stdin --region cn
+```
+
 ### Wrong region
 
 Use a one-time override:
@@ -219,6 +234,7 @@ yeelight-home home select --house-id <house-id>
 Run:
 
 ```sh
+yeelight-home doctor
 yeelight-home doctor --json
 ```
 

package/INSTALL.md

@@ -6,18 +6,48 @@ This document is for users installing the standalone `yeelight-home` CLI.
 
 ```sh
 yeelight-home version
+yeelight-home version --json
+yeelight-home doctor
 yeelight-home doctor --json
+yeelight-home doctor --json --online
 ```
 
+`version --json` reports build metadata. `doctor` prints a human-readable diagnostic summary. `doctor --json` reports the same data as a machine-readable object: running CLI version, executable path, `PATH` lookup result, npm wrapper path when applicable, and local package-manager diagnostics. Homebrew diagnostics distinguish formula and cask installs.
+`doctor --online` additionally checks public GitHub Release, npm registry, and Yeelight Homebrew tap latest versions. Use it when npm, Homebrew, Scoop, or a host application seems to be launching an older binary than the latest release. If one online channel reports `ok=false`, continue using the other channel results and the local warnings; public registries can rate-limit or temporarily fail independently.
+Text output includes an `Install source summary` section that calls out whether `PATH` resolves an npm wrapper and which npm/Homebrew versions are installed.
+If it includes `path_lookup_differs_from_running_executable`, the shell or host application is resolving a different `yeelight-home` binary than the one being inspected.
+If it includes `npm_wrapper_differs_from_path_lookup`, the active npm wrapper is not the same wrapper that the current shell resolves from `PATH`; restart the host shell, check `command -v yeelight-home`, or remove the stale channel.
+If it includes `npm_global_package_version_differs_from_runtime_version`, the globally installed npm wrapper version differs from the Runtime binary it launches or from the binary currently being inspected. Upgrade or reinstall through one channel and restart the host shell.
+If it includes `npm_global_package_behind_latest`, the npm registry has a newer published package than the globally installed wrapper. Run `npm install -g yeelight-home@latest` and restart the shell or Skill host.
+If it includes `homebrew_package_version_differs_from_runtime_version`, refresh Homebrew metadata and upgrade the formula or remove the older channel from `PATH`.
+If it includes `homebrew_formula_version_differs_from_runtime_version`, refresh Homebrew metadata and upgrade the formula with `brew update && brew upgrade yeelight-home`.
+If it includes `homebrew_cask_version_differs_from_runtime_version`, refresh Homebrew metadata and upgrade the cask with `brew update && brew upgrade --cask yeelight-home`.
+If it includes `homebrew_formula_behind_latest`, refresh Homebrew metadata with `brew update`, then run `brew upgrade yeelight-home` or reinstall from `Yeelight/tap`.
+If it includes `homebrew_cask_behind_latest`, refresh Homebrew metadata with `brew update`, then run `brew upgrade --cask yeelight-home` or reinstall from `Yeelight/tap`.
+Use `install.remediations` in JSON output, or the `Suggested fixes` section in text output, for the safest next command for the current machine.
+
 After installing, authenticate locally:
 
 ```sh
-yeelight-home auth status --json
+yeelight-home auth status
 yeelight-home auth login --qr
 ```
 
 The default region is `cn`. Use `--region sg`, `--region us`, or `--region eu` when needed.
 
+If QR login is not possible but you have an approved token, import it locally without putting it in shell history:
+
+```sh
+printf '%s' "$YEELIGHT_TOKEN" | yeelight-home auth token set --stdin --region cn
+```
+
+For dev validation:
+
+```sh
+printf '%s' "$YEELIGHT_DEV_TOKEN" | yeelight-home auth token set --stdin --profile dev --region dev --json
+yeelight-home home list --profile dev --region dev --json
+```
+
 ## GitHub Releases
 
 GitHub Releases are the canonical fallback channel for all platforms.
@@ -109,6 +139,7 @@ If Winget cannot find the package yet, use GitHub Releases, Scoop, Homebrew on W
 ## npm Wrapper
 
 The npm package is a thin launcher. It downloads the matching GitHub Release binary on install or first run and verifies the checksum.
+When it launches the downloaded binary, it sets `YEELIGHT_HOME_NPM_WRAPPER_PATH` so `yeelight-home doctor --json` can report `install.npmWrapper` and `install.npmWrapperResolved`. This helps diagnose stale npm wrappers, Homebrew shadows, and host applications using a different `PATH`.
 
 ```sh
 npm install -g yeelight-home
@@ -227,6 +258,34 @@ $env:YEELIGHT_HOME_BIN=(Get-Command yeelight-home).Source
 
 Restart the host application after changing user PATH.
 
+## Multiple Install Sources
+
+Use one primary install channel per machine when possible. Multiple global installers can leave an older `yeelight-home` earlier on `PATH`.
+
+Check the active binary:
+
+```sh
+command -v yeelight-home
+yeelight-home version
+yeelight-home doctor --json
+```
+
+Typical ownership:
+
+- npm global installs create a launcher under the Node prefix, for example `/opt/homebrew/bin/yeelight-home`.
+- Homebrew installs under the Homebrew prefix, but it may not be active if an npm launcher with the same name is earlier on `PATH`.
+- GitHub install scripts copy the binary to `YEELIGHT_HOME_INSTALL_DIR`, `$HOME/.local/bin`, or another selected directory.
+
+Upgrade the channel that owns the active binary:
+
+```sh
+npm install -g yeelight-home@latest
+brew update && brew upgrade yeelight-home
+scoop update yeelight-home
+```
+
+When switching channels, uninstall or unlink the old channel first so `PATH` resolves one expected binary.
+
 ## Uninstall
 
 Remove the binary through the same installer or package manager that installed it.

package/README.md

@@ -54,6 +54,7 @@ Debian, Ubuntu, Fedora, Arch, AUR, Snap, Docker, GHCR, Docker Hub, and Winget ch
 
 ```sh
 yeelight-home version
+yeelight-home doctor
 yeelight-home doctor --json
 yeelight-home auth status --json
 yeelight-home auth login --qr
@@ -64,13 +65,14 @@ yeelight-home home select --house-id <house-id>
 
 The default region is `cn`. Pass `--region sg`, `--region us`, or `--region eu` when your Yeelight account belongs to another cloud region.
 
-For non-interactive local setup, import a token outside chat:
+For non-interactive local setup, import a token outside chat. Prefer `--stdin` in real shells so the token is not saved in shell history:
 
 ```sh
-yeelight-home auth token set --token <access-token> --region cn
+printf '%s' "$YEELIGHT_TOKEN" | yeelight-home auth token set --stdin --region cn
+printf '%s' "$YEELIGHT_DEV_TOKEN" | yeelight-home auth token set --stdin --profile dev --region dev --json
 ```
 
-Token-only setup is valid. `houseId` is optional profile metadata for the default home. Account-level commands such as `auth status`, `doctor`, `api smoke`, `home list`, `home.summary`, `home.search`, and `account.info` do not require it. House-scoped operations such as device, room, scene, group, gateway, favorite, and automation actions require a `houseId` from the request, `YEELIGHT_HOME_HOUSE_ID`, or the selected profile.
+Token-only setup is valid. `houseId` is optional profile metadata for the default home. In other words, houseId is optional until you run a house-scoped command. Account-level commands such as `auth status`, `doctor`, `api smoke`, `home list`, `home.summary`, `home.search`, and `account.info` do not require it. House-scoped operations such as device, room, scene, group, gateway, favorite, and automation actions require a `houseId` from the request, `YEELIGHT_HOME_HOUSE_ID`, or the selected profile.
 
 Do not paste tokens into AI chat. The CLI stores tokens locally and never prints token values in normal status or doctor output.
 
@@ -108,19 +110,35 @@ See [CONFIG.md](CONFIG.md) for full command and precedence details.
 ### `doctor`
 
 ```sh
-yeelight-home doctor --json [--profile <name>] [--region <region>] [--house-id <id>]
+yeelight-home doctor [--json] [--online] [--profile <name>] [--region <region>] [--house-id <id>]
 ```
 
-Reports installation, config directories, selected profile, selected region, selected home, token presence, and warnings. Token values are never printed.
+Reports installation, config directories, selected profile, selected region, selected home, token presence, and warnings. Without `--json`, it prints a human-readable diagnostic summary. With `--json`, it prints the machine-readable diagnostic object. Token values are never printed.
 The selected home may be empty; that is healthy for token-only account-level use.
+The `install` object includes the running CLI version, executable path, `PATH` lookup result, OS, architecture, and npm wrapper path when launched through the npm package. If `path_lookup_differs_from_running_executable` appears, a shell, package manager, or Skill host is resolving a different `yeelight-home` binary than the one currently being inspected.
+It also includes `packageManagers.npm` and `packageManagers.homebrew` when those tools are available. Homebrew diagnostics include separate `formula` and `cask` entries so PATH drift can be traced to the exact channel. Use those fields to find stale npm wrappers, Homebrew formula installs, or Homebrew cask installs that differ from the Runtime binary on `PATH`.
+When launched by the npm wrapper, `doctor --json` reports `install.npmWrapper` and `install.npmWrapperResolved`. `npm_wrapper_differs_from_path_lookup` means the running wrapper is not the same file that the current shell would resolve from `PATH`; restart the host shell or remove the stale channel.
+Text output includes `Install source summary` to make the active PATH channel and installed npm/Homebrew versions visible without parsing JSON.
+Pass `--online` when you want `doctor` to query the public GitHub Release, npm registry, and Yeelight Homebrew tap latest versions. This is intentionally opt-in so default diagnostics stay fast and offline-friendly. A single online channel with `ok=false` means that channel could not be checked; other successful channel results and local warnings remain useful.
+The `install.remediations` array and the text-mode `Suggested fixes` section provide safe next commands for the detected local install shape.
+
+### `version`
+
+```sh
+yeelight-home version
+yeelight-home version --json
+```
+
+`version --json` reports build metadata: version, commit, build date, OS, and architecture.
 
 ### `auth status`
 
 ```sh
-yeelight-home auth status --json [--profile <name>]
+yeelight-home auth status [--json] [--profile <name>] [--region <region>] [--house-id <id>]
 ```
 
 Reports whether the selected profile has a usable local credential.
+Without `--json`, it prints a human-readable summary. With `--json`, it prints the machine-readable status object.
 
 ### `auth login`
 
@@ -134,17 +152,18 @@ Starts the local QR login flow. If `--region` is omitted, `cn` is used.
 ### `auth token set`
 
 ```sh
-yeelight-home auth token set --token <access-token> [--profile <name>] [--region <region>] [--house-id <id>] [--json]
+yeelight-home auth token set (--token <access-token>|--stdin) [--profile <name>] [--region <region>] [--house-id <id>] [--json]
 ```
 
 Imports a token into the local credential store. It never writes the token into the profile metadata file.
+Prefer `--stdin` in real shells to avoid saving secrets in command history.
 `--house-id` is optional. Omit it when you only need account-level commands or plan to select a home later.
 
 ### `profile`
 
 ```sh
 yeelight-home profile list [--json]
-yeelight-home profile show [--profile <name>] [--json]
+yeelight-home profile show [--json] [--profile <name>] [--region <region>] [--house-id <id>]
 yeelight-home profile use --profile <name> [--region <region>] [--house-id <id>] [--json]
 yeelight-home profile delete --profile <name> [--json]
 ```
@@ -156,12 +175,21 @@ The selected home can be empty in a profile.
 
 ```sh
 yeelight-home config get [--profile <name>] [--region <region>] [--house-id <id>] [--json]
+yeelight-home config list [--profile <name>] [--json]
 yeelight-home config set [--profile <name>] [--region <region>] [--house-id <id>] [--qr-device <mac>] [--json]
 yeelight-home config unset [--profile <name>] [--region] [--house-id] [--qr-device] [--json]
 ```
 
 `config` changes non-secret profile metadata only.
 
+### `completion`
+
+```sh
+yeelight-home completion <bash|zsh|fish|powershell>
+```
+
+Prints a shell completion script to stdout. Install it using the standard mechanism for your shell.
+
 ### `home`
 
 ```sh
@@ -183,18 +211,22 @@ Reads a SkillRequest JSON object from stdin and writes a SkillResponse JSON obje
 ### `api smoke`
 
 ```sh
-yeelight-home api smoke --json [--profile <name>] [--region <region>] [--house-id <id>]
+yeelight-home api smoke [--json] [--profile <name>] [--region <region>] [--house-id <id>]
 ```
 
 Runs a local cloud smoke check using the selected credential. This is intended for installation and support diagnostics.
+Without `--json`, it prints a human-readable summary. With `--json`, it prints account and home-list check details for support automation.
 
 ## Skill Integration
 
 Skill wrapper lookup order:
 
 1. `YEELIGHT_HOME_BIN`
-2. Development-only source checkout binary
-3. `yeelight-home` on `PATH`
+2. `yeelight-home` on `PATH`
+
+Published Skill packages do not carry or auto-discover Runtime source-tree
+binaries. Use `YEELIGHT_HOME_BIN` for a deliberate local override, or install
+the public CLI so it is available on `PATH`.
 
 When the Runtime is missing, install it from a published public channel, then run:
 
@@ -204,6 +236,12 @@ yeelight-home auth login --qr
 yeelight-home home list --json
 ```
 
+If QR login is unavailable and the user already has an approved token, import it locally outside chat:
+
+```sh
+printf '%s' "$YEELIGHT_TOKEN" | yeelight-home auth token set --stdin --region cn
+```
+
 Skills must not call raw URLs, raw headers, curl, compatibility services, or token-bearing commands.
 
 ## Release And Packaging

package/bin/yeelight-home.js

@@ -13,7 +13,11 @@ if (!result.ok) {
 
 const child = spawnSync(result.binaryPath, process.argv.slice(2), {
   stdio: "inherit",
-  windowsHide: false
+  windowsHide: false,
+  env: {
+    ...process.env,
+    YEELIGHT_HOME_NPM_WRAPPER_PATH: __filename
+  }
 });
 
 if (child.error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeelight-home",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Local Yeelight Home Runtime CLI installer and launcher.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/Yeelight/yeelight-home#readme",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "postinstall": "node npm/install.js",
-    "smoke": "node bin/yeelight-home.js version"
+    "smoke": "node bin/yeelight-home.js version --json"
   },
   "engines": {
     "node": ">=18"