yeelight-home 0.1.0

package/CONFIG.md

@@ -0,0 +1,63 @@
+# Configuration
+
+## Precedence
+
+Runtime configuration is resolved in this order:
+
+1. Command flags: `--profile`, `--region`, `--client-id`, `--house-id`
+2. Environment variables: `YEELIGHT_HOME_PROFILE`, `YEELIGHT_CLOUD_REGION`, `YEELIGHT_HOME_CLIENT_ID`, `YEELIGHT_HOME_HOUSE_ID`, `YEELIGHT_HOME_ACCESS_TOKEN`
+3. Active profile, profile metadata, and credential store
+4. Defaults: profile `default`, region `dev`
+
+`YEELIGHT_API_BASE_URL` is a developer override for local testing. Do not expose it in Skill responses or user-facing automation.
+
+## Profiles
+
+```sh
+yeelight-home profile list --json
+yeelight-home profile show --profile default --json
+yeelight-home profile use --profile family --region cn --client-id <client-id> --house-id <house-id>
+yeelight-home profile delete --profile family
+```
+
+`profile use` saves metadata and sets the active local profile. Profile metadata is stored in `~/.yeelight-home/config/profiles.json` by default. It contains active profile, region, client id, house id, and QR device metadata. It must not contain access tokens.
+
+## Credentials
+
+Preferred login:
+
+```sh
+yeelight-home auth login --qr --region cn --profile default
+```
+
+Manual token import:
+
+```sh
+yeelight-home auth token set --profile default --token <access-token> --region cn --client-id <client-id> --house-id <house-id>
+```
+
+Status:
+
+```sh
+yeelight-home auth status --json
+```
+
+Tokens are loaded from `YEELIGHT_HOME_ACCESS_TOKEN` first, then from the local credential store. Status and doctor output only report whether a token is present.
+
+## Home Selection
+
+```sh
+yeelight-home home list --json
+yeelight-home home select --house-id <house-id> --profile default
+```
+
+`home select` changes only local profile metadata. It does not modify Yeelight cloud home data.
+
+## Diagnostics
+
+```sh
+yeelight-home doctor --json
+yeelight-home api smoke --json --region cn --profile default
+```
+
+`doctor` checks local installation, paths, profile, region, token presence, and Runtime storage status. `api smoke` performs read-only cloud checks when credentials are configured.

package/DISTRIBUTION.md

@@ -0,0 +1,38 @@
+# Distribution
+
+`yeelight-home` is distributed as a standalone CLI. The public source and release repository is `Yeelight/yeelight-home`; Skill packages should depend on the installed CLI through `YEELIGHT_HOME_BIN` or `PATH`.
+
+## Channels
+
+| Channel | Status | User install path |
+| --- | --- | --- |
+| GitHub Releases | Published | `curl -fsSL https://github.com/yeelight/yeelight-home/releases/latest/download/install.sh \| sh` |
+| Homebrew | Published | `brew install Yeelight/tap/yeelight-home` |
+| Scoop | Published | `scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket && scoop install yeelight-home` |
+| Debian package | Published | Download `yeelight-home_0.1.0_amd64.deb` or `yeelight-home_0.1.0_arm64.deb` from GitHub Releases |
+| Winget | Submitted | `winget install Yeelight.yeelight-home` after microsoft/winget-pkgs PR 392555 is merged |
+| npm | Published | `npm install -g yeelight-home` |
+
+## Repository Layout Policy
+
+- Keep `Yeelight/yeelight-home` as the public Runtime source and release repository.
+- Keep `Yeelight/homebrew-tap` as a shared Homebrew tap for all Yeelight formulas. This is conventional because GitHub taps use the `homebrew-` prefix for the short `brew tap Yeelight/tap` form.
+- Scoop does not require a Yeelight organization repository or a dedicated repository. It only needs a Git bucket repository containing JSON manifests. `Yeelight/scoop-bucket` is valid and already published; if repository count becomes a problem, future Scoop manifests can move into a consolidated distribution repository, but the existing bucket should remain as a compatibility pointer.
+- Winget does not require a Yeelight repository. Official publication happens through `microsoft/winget-pkgs`; any personal fork is only a PR workspace.
+- npm does not require a GitHub repository. It requires an npm account or automation token with permission to publish `yeelight-home` or the chosen scoped package.
+
+## npm Package Model
+
+The npm package is a thin installer and launcher:
+
+1. `postinstall` downloads the matching GitHub Release asset for the user's OS and CPU.
+2. The asset checksum is verified against `checksums.txt`.
+3. The binary is cached under the user's local cache directory.
+4. The npm `yeelight-home` binary delegates all arguments to the cached Go Runtime binary.
+
+Environment overrides:
+
+- `YEELIGHT_HOME_REPO=owner/repo`
+- `YEELIGHT_HOME_VERSION=yeelight-home-v0.1.0` or `latest`
+- `YEELIGHT_HOME_NPM_CACHE_DIR=/custom/cache`
+- `YEELIGHT_HOME_NPM_SKIP_INSTALL=1`

package/INSTALL.md

@@ -0,0 +1,80 @@
+# Installation
+
+## GitHub Releases
+
+macOS and Linux:
+
+```sh
+curl -fsSL https://github.com/yeelight/yeelight-home/releases/latest/download/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+iwr https://github.com/yeelight/yeelight-home/releases/latest/download/install.ps1 -UseB | iex
+```
+
+Override the install source when testing a fork:
+
+```sh
+YEELIGHT_HOME_REPO=owner/repo YEELIGHT_HOME_VERSION=yeelight-home-v1.0.0 sh install.sh
+```
+
+PowerShell:
+
+```powershell
+$env:YEELIGHT_HOME_REPO="owner/repo"
+$env:YEELIGHT_HOME_VERSION="yeelight-home-v1.0.0"
+.\install.ps1
+```
+
+## Package Managers
+
+Homebrew:
+
+```sh
+brew install Yeelight/tap/yeelight-home
+```
+
+Scoop:
+
+```powershell
+scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket
+scoop install yeelight-home
+```
+
+Debian/Ubuntu:
+
+```sh
+curl -LO https://github.com/Yeelight/yeelight-home/releases/download/yeelight-home-v0.1.0/yeelight-home_0.1.0_amd64.deb
+sudo apt install ./yeelight-home_0.1.0_amd64.deb
+```
+
+Winget:
+
+- Submitted for review: https://github.com/microsoft/winget-pkgs/pull/392555
+- After merge: `winget install Yeelight.yeelight-home`
+
+npm:
+
+```sh
+npm install -g yeelight-home
+```
+
+## Verify
+
+```sh
+yeelight-home version
+yeelight-home doctor --json
+```
+
+## Uninstall
+
+Remove the binary from the install directory and delete local Runtime data only when you intend to remove credentials and local preferences:
+
+```sh
+rm -f /usr/local/bin/yeelight-home
+rm -rf ~/.yeelight-home
+```
+
+On Windows, remove `%LOCALAPPDATA%\Programs\YeelightHome\bin\yeelight-home.exe` and remove that directory from the user `Path` if it was added by the installer.

package/README.md

@@ -0,0 +1,75 @@
+# yeelight-home
+
+`yeelight-home` is the local Runtime CLI for Yeelight smart-home Skills. It keeps credentials on the user's machine, resolves semantic Skill requests, calls Yeelight cloud APIs directly, and returns redacted structured results.
+
+## Install
+
+Install from the public runtime release repository:
+
+```sh
+curl -fsSL https://github.com/yeelight/yeelight-home/releases/latest/download/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+iwr https://github.com/yeelight/yeelight-home/releases/latest/download/install.ps1 -UseB | iex
+```
+
+Homebrew:
+
+```sh
+brew install Yeelight/tap/yeelight-home
+```
+
+Scoop:
+
+```powershell
+scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket
+scoop install yeelight-home
+```
+
+Debian/Ubuntu users can download the `yeelight-home_0.1.0_amd64.deb` or `yeelight-home_0.1.0_arm64.deb` asset from the GitHub Release and install it with `apt` or `dpkg`.
+
+Npm:
+
+```sh
+npm install -g yeelight-home
+```
+
+Winget publication is submitted for review at https://github.com/microsoft/winget-pkgs/pull/392555. Until it is merged, use GitHub Releases, Homebrew, Scoop, or set `YEELIGHT_HOME_BIN` to an absolute `yeelight-home` executable path.
+
+## Quick Start
+
+```sh
+yeelight-home version
+yeelight-home auth status --json
+yeelight-home auth login --qr --region dev
+yeelight-home home list --json
+yeelight-home home select --house-id <house-id>
+yeelight-home doctor --json
+```
+
+For non-interactive local setup, import a token outside chat:
+
+```sh
+yeelight-home auth token set --token <access-token> --region cn --client-id <client-id> --house-id <house-id>
+```
+
+Do not paste tokens into AI chat. The CLI stores tokens in the system credential store when available, and otherwise in a protected local credential fallback under the Runtime config directory.
+
+## Skill Integration
+
+Skills should call only:
+
+```sh
+yeelight-home invoke --stdin
+```
+
+The Yeelight Smart Home Skill wrapper resolves the Runtime in this order:
+
+1. `YEELIGHT_HOME_BIN`
+2. development-only bundled binary when present in a source checkout
+3. `yeelight-home` on `PATH`
+
+No Skill should call raw URLs, headers, curl, MCP compatibility services, or token-bearing commands.

package/npm/bin/yeelight-home.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { ensureRuntimeBinary } = require("../lib/runtime-installer");
+
+const result = ensureRuntimeBinary();
+if (!result.ok) {
+  console.error(result.message);
+  process.exit(result.code || 1);
+}
+
+const child = spawnSync(result.binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: false
+});
+
+if (child.error) {
+  console.error(child.error.message);
+  process.exit(1);
+}
+
+process.exit(child.status === null ? 1 : child.status);

package/npm/install.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { ensureRuntimeBinary } = require("./lib/runtime-installer");
+
+if (process.env.YEELIGHT_HOME_NPM_SKIP_INSTALL === "1") {
+  process.exit(0);
+}
+
+const result = ensureRuntimeBinary();
+if (!result.ok) {
+  console.error(result.message);
+  process.exit(result.code || 1);
+}
+
+console.log(`yeelight-home runtime installed at ${result.binaryPath}`);

package/npm/lib/runtime-installer.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { spawnSync } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const packageInfo = require(path.join(packageRoot, "package.json"));
+
+function ensureRuntimeBinary() {
+  let target;
+  try {
+    target = resolveTarget();
+  } catch (error) {
+    return { ok: false, code: 2, message: error.message };
+  }
+
+  const binaryPath = resolveBinaryPath(target);
+  if (fs.existsSync(binaryPath)) {
+    return { ok: true, binaryPath };
+  }
+
+  try {
+    installRuntime(target, binaryPath);
+  } catch (error) {
+    return {
+      ok: false,
+      code: 1,
+      message: `failed to install yeelight-home runtime: ${error.message}`
+    };
+  }
+
+  return { ok: true, binaryPath };
+}
+
+function resolveTarget() {
+  const platformMap = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows"
+  };
+  const archMap = {
+    x64: "amd64",
+    arm64: "arm64"
+  };
+
+  const goos = platformMap[process.platform];
+  const goarch = archMap[process.arch];
+  if (!goos || !goarch) {
+    throw new Error(`unsupported platform: ${process.platform}/${process.arch}`);
+  }
+
+  const repo = process.env.YEELIGHT_HOME_REPO || "Yeelight/yeelight-home";
+  const version = process.env.YEELIGHT_HOME_VERSION || `yeelight-home-v${packageInfo.version}`;
+  const extension = goos === "windows" ? "zip" : "tar.gz";
+  const assetName = `yeelight-home-${goos}-${goarch}.${extension}`;
+  const releasePath = version === "latest" ? "latest/download" : `download/${version}`;
+
+  return {
+    repo,
+    version,
+    goos,
+    goarch,
+    assetName,
+    binaryName: goos === "windows" ? "yeelight-home.exe" : "yeelight-home",
+    assetUrl: `https://github.com/${repo}/releases/${releasePath}/${assetName}`,
+    checksumsUrl: `https://github.com/${repo}/releases/${releasePath}/checksums.txt`
+  };
+}
+
+function resolveBinaryPath(target) {
+  const cacheRoot = process.env.YEELIGHT_HOME_NPM_CACHE_DIR || defaultCacheRoot();
+  const repoKey = target.repo.replace(/[^A-Za-z0-9_.-]+/g, "-");
+  return path.join(cacheRoot, repoKey, target.version, `${target.goos}-${target.goarch}`, target.binaryName);
+}
+
+function defaultCacheRoot() {
+  if (process.platform === "win32" && process.env.LOCALAPPDATA) {
+    return path.join(process.env.LOCALAPPDATA, "YeelightHome", "npm");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Caches", "yeelight-home", "npm");
+  }
+  return path.join(os.homedir(), ".cache", "yeelight-home", "npm");
+}
+
+function installRuntime(target, binaryPath) {
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "yeelight-home-npm-"));
+  try {
+    const assetPath = path.join(workDir, target.assetName);
+    const checksumsPath = path.join(workDir, "checksums.txt");
+    downloadFile(target.assetUrl, assetPath);
+    downloadFile(target.checksumsUrl, checksumsPath);
+    verifyChecksum(assetPath, checksumsPath, target.assetName);
+
+    fs.mkdirSync(path.dirname(binaryPath), { recursive: true });
+    if (target.goos === "windows") {
+      extractZip(assetPath, target.binaryName, binaryPath, workDir);
+    } else {
+      extractTarGz(assetPath, target.binaryName, binaryPath, workDir);
+      fs.chmodSync(binaryPath, 0o755);
+    }
+  } finally {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+function downloadFile(url, outputPath) {
+  const response = spawnSync(process.execPath, [
+    "-e",
+    `
+      const fs = require("node:fs");
+      const https = require("node:https");
+      const url = process.argv[1];
+      const out = process.argv[2];
+      function get(current, redirects) {
+        https.get(current, res => {
+          if ([301, 302, 303, 307, 308].includes(res.statusCode)) {
+            if (redirects <= 0) throw new Error("too many redirects");
+            res.resume();
+            get(new URL(res.headers.location, current).toString(), redirects - 1);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            console.error("download failed: " + res.statusCode + " " + current);
+            process.exit(1);
+          }
+          const file = fs.createWriteStream(out, { mode: 0o600 });
+          res.pipe(file);
+          file.on("finish", () => file.close(() => process.exit(0)));
+        }).on("error", err => {
+          console.error(err.message);
+          process.exit(1);
+        });
+      }
+      get(url, 5);
+    `,
+    url,
+    outputPath
+  ], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
+
+  if (response.status !== 0) {
+    throw new Error((response.stderr || "").trim() || `download failed: ${url}`);
+  }
+}
+
+function verifyChecksum(assetPath, checksumsPath, assetName) {
+  const checksums = fs.readFileSync(checksumsPath, "utf8").split(/\r?\n/);
+  let expected = "";
+  for (const line of checksums) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length >= 2 && parts[1] === assetName) {
+      expected = parts[0];
+      break;
+    }
+  }
+  if (!expected) {
+    throw new Error(`checksum not found for ${assetName}`);
+  }
+
+  const actual = crypto.createHash("sha256").update(fs.readFileSync(assetPath)).digest("hex");
+  if (actual !== expected) {
+    throw new Error(`checksum mismatch for ${assetName}`);
+  }
+}
+
+function extractTarGz(assetPath, binaryName, binaryPath, workDir) {
+  const extractDir = path.join(workDir, "tar");
+  fs.mkdirSync(extractDir, { recursive: true });
+  const result = spawnSync("tar", ["-xzf", assetPath, "-C", extractDir], {
+    stdio: ["ignore", "ignore", "pipe"],
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || "").trim() || "tar extraction failed");
+  }
+  const extractedBinary = path.join(extractDir, binaryName);
+  if (!fs.existsSync(extractedBinary)) {
+    throw new Error(`${binaryName} not found in ${path.basename(assetPath)}`);
+  }
+  fs.copyFileSync(extractedBinary, binaryPath);
+}
+
+function extractZip(assetPath, binaryName, binaryPath, workDir) {
+  const extractDir = path.join(workDir, "zip");
+  fs.mkdirSync(extractDir, { recursive: true });
+  const script = `Expand-Archive -LiteralPath '${assetPath.replace(/'/g, "''")}' -DestinationPath '${extractDir.replace(/'/g, "''")}' -Force`;
+  const result = spawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script], {
+    stdio: ["ignore", "ignore", "pipe"],
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || "").trim() || "PowerShell Expand-Archive failed");
+  }
+  const extractedBinary = path.join(extractDir, binaryName);
+  if (!fs.existsSync(extractedBinary)) {
+    throw new Error(`${binaryName} not found in ${path.basename(assetPath)}`);
+  }
+  fs.copyFileSync(extractedBinary, binaryPath);
+}
+
+module.exports = {
+  ensureRuntimeBinary
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "yeelight-home",
+  "version": "0.1.0",
+  "description": "Local Yeelight Home Runtime CLI installer and launcher.",
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/Yeelight/yeelight-home#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yeelight/yeelight-home.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Yeelight/yeelight-home/issues"
+  },
+  "bin": {
+    "yeelight-home": "npm/bin/yeelight-home.js"
+  },
+  "files": [
+    "npm/",
+    "README.md",
+    "INSTALL.md",
+    "CONFIG.md",
+    "DISTRIBUTION.md"
+  ],
+  "scripts": {
+    "postinstall": "node npm/install.js",
+    "smoke": "node npm/bin/yeelight-home.js version"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}