Merge pull request #62 from OpenWonderLabs/feat/claude-code-setup

chenliuyun · web-flow · commit 6ab54ffac840 · 2026-05-29T14:32:28.000+08:00
feat: claude-code setup command + plugin marketplace fixes (v3.7.7)
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,14 +1,15 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "switchbot",
+  "owner": {
+    "name": "OpenWonderLabs",
+    "email": "developer@wondertechlabs.com"
+  },
   "plugins": [
     {
       "name": "switchbot",
-      "source": "./packages/codex-plugin/plugins/switchbot",
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
+      "source": "./packages/claude-code-plugin/plugins/switchbot",
+      "description": "Control SwitchBot smart-home devices from Claude Code via MCP.",
       "category": "Productivity"
     }
   ]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,18 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [3.7.7]
+
+### Added
+
+- **`switchbot claude-code setup` command** — 6-step pipeline that bootstraps Claude Code integration end-to-end: verify `claude` CLI on PATH, optionally install `@switchbot/openapi-cli`, register the MCP server via `claude mcp add --scope user`, authenticate, and run a health check. Supports `--yes` (non-interactive), `--skip`, `--dry-run`, `--json`. Paste `npx @switchbot/openapi-cli claude-code setup` into Claude Code chat to set up without opening a terminal.
+- **Claude Code Plugin Marketplace support** — `.claude-plugin/marketplace.json` now correctly points to `packages/claude-code-plugin/plugins/switchbot` so `/plugin marketplace add OpenWonderLabs/switchbot-openapi-cli` followed by `/plugin install switchbot@switchbot` works end-to-end. `smoke-codex-git-sparse.mjs` extended to validate both the Claude Code and Codex marketplace entry points.
+
+### Fixed
+
+- **`switchbot auth login` clears device/status cache** — switching accounts no longer returns stale data from the previous account's cache. `clearCache()` and `clearStatusCache()` are called immediately after new credentials are saved.
+- **`codex setup --help` / `claude-code setup --help`** — both commands now list `--dry-run` and `--json` under a "Global flags that also apply to this command" section so users do not have to discover them from the README.
+
 ## [3.7.5]
 
 ### Fixed
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -28,3 +28,14 @@ Example body:
 The CHANGELOG itself follows Keep a Changelog + SemVer, with a
 **Changed (BREAKING)** section whenever a release introduces a breaking
 change (even in a patch version).
+
+## Plugin hook strategies
+
+The two plugin packages use different `onInstall` hook strategies — this is intentional:
+
+| Package | Hook command | Reason |
+|---------|-------------|--------|
+| `packages/claude-code-plugin` | `node ../bin/auth.js` (relative path) | Claude Code installs the full npm package; `bin/` is always adjacent. |
+| `packages/codex-plugin` | `switchbot-codex-auth` (global binary) | Codex may install only the `plugins/switchbot/` sub-directory, placing it in `~/.codex/plugins/switchbot/`. A relative path to `bin/auth.js` would escape the plugin directory and fail. Using the globally-installed binary works regardless of install layout. |
+
+When changing either hook, preserve this distinction. Do not "unify" them without first verifying that both installation layouts still resolve the hook correctly.
diff --git a/README.md b/README.md
@@ -95,9 +95,16 @@ Then restart Codex and confirm it's working.
 **Or install directly:**
 
 ```bash
-npm install -g @switchbot/codex-plugin
-switchbot-codex-install        # registers the plugin with Codex
-switchbot auth login           # browser OAuth — saves to OS keychain
+npm install -g @switchbot/openapi-cli @switchbot/codex-plugin
+switchbot codex setup           # one-shot bootstrap: register, auth, verify
+```
+
+**Or install via Codex Plugin Marketplace** (requires Codex CLI with marketplace support):
+
+```bash
+codex plugin marketplace add OpenWonderLabs/switchbot-openapi-cli
+codex plugin add switchbot@switchbot
+switchbot auth login
 ```
 
 ---
@@ -107,9 +114,10 @@ switchbot auth login           # browser OAuth — saves to OS keychain
 The OpenClaw skill is published to npm as [`@switchbot/openclaw-skill`](https://www.npmjs.com/package/@switchbot/openclaw-skill).
 
 ```bash
-openclaw plugins install @switchbot/openclaw-skill   # via OpenClaw plugin manager (recommended)
+npm install -g @switchbot/openapi-cli               # required CLI
+openclaw plugins install @switchbot/openclaw-skill  # via OpenClaw plugin manager (recommended)
 # or
-npm install -g @switchbot/openclaw-skill             # via npm
+npm install -g @switchbot/openclaw-skill            # via npm
 
 switchbot-openclaw setup   # verify CLI install and credentials
 switchbot auth login       # browser OAuth — saves to OS keychain
@@ -121,27 +129,40 @@ switchbot auth login       # browser OAuth — saves to OS keychain
 
 ## Claude Code integration
 
-**Step 0 — verify first.** If the MCP server is already configured (e.g. via a managed environment or prior setup), no additional steps are needed:
+**Already configured? Paste into Claude Code chat:**
 
-```bash
-switchbot doctor --json
+```
+Is my SwitchBot integration working? Please check and list my devices.
+```
+
+Claude will call `account_overview` or `switchbot doctor` to verify — no terminal needed.
+
+**Fresh setup — paste into Claude Code chat:**
+
+```
+Please set up my SwitchBot integration by running:
+npx @switchbot/openapi-cli claude-code setup
 ```
 
-If 24 tools are visible and the integration is healthy, you're done.
+Claude will run the setup command via the Bash tool. It installs the CLI if missing, registers the MCP server via `claude mcp add --scope user`, and opens a browser login if credentials are not yet configured. Restart Claude Code afterwards to load the MCP tools.
 
-**Fresh setup:**
+**Or run manually in your terminal:**
 
 ```bash
 npm install -g @switchbot/openapi-cli
-claude mcp add switchbot -- switchbot mcp serve --tools all
-switchbot auth login                     # browser OAuth — saves to OS keychain
+switchbot claude-code setup
 ```
 
-Run `switchbot doctor --json` afterwards to confirm everything is working.
+The optional skill package [`@switchbot/claude-code-plugin`](https://www.npmjs.com/package/@switchbot/claude-code-plugin) bundles the SKILL.md context document. Install it only if your environment does not already load the skill automatically.
 
-The optional skill package [`@switchbot/claude-code-plugin`](https://www.npmjs.com/package/@switchbot/claude-code-plugin) bundles the SKILL.md context document and install hook. Install it only if your environment does not already load the skill automatically.
+**Or install via Claude Code Plugin Marketplace** (requires Claude Code with plugin marketplace support enabled):
+
+```
+/plugin marketplace add OpenWonderLabs/switchbot-openapi-cli
+/plugin install switchbot@switchbot
+```
 
-**Note:** The root `marketplace.json` file in this repo is for Codex CLI Route B (git sparse clone) and points to the Codex plugin at `packages/codex-plugin/plugins/switchbot`. Claude Code users register via `claude mcp add` and do not use this file.
+**Note:** The root `marketplace.json` in this repo is for Codex CLI Route B (git sparse clone) and points to `packages/codex-plugin/plugins/switchbot`. The `.claude-plugin/marketplace.json` is for Claude Code Plugin Marketplace and points to `packages/claude-code-plugin/plugins/switchbot`.
 
 ---
 
diff --git a/marketplace.json b/marketplace.json
@@ -1,9 +1,17 @@
 {
   "name": "switchbot",
+  "interface": {
+    "displayName": "SwitchBot"
+  },
   "plugins": [
     {
       "name": "switchbot",
-      "source": "./packages/codex-plugin/plugins/switchbot"
+      "source": "./packages/codex-plugin/plugins/switchbot",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.7.6",
+  "version": "3.7.7",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",
diff --git a/packages/claude-code-plugin/.claude-plugin/marketplace.json b/packages/claude-code-plugin/.claude-plugin/marketplace.json
@@ -15,7 +15,7 @@
         "name": "OpenWonderLabs"
       },
       "source": "./plugins/switchbot",
-      "category": "productivity",
+      "category": "Productivity",
       "homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli"
     }
   ]
diff --git a/packages/claude-code-plugin/package.json b/packages/claude-code-plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/claude-code-plugin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "SwitchBot Claude Code plugin — wires Claude Code to the SwitchBot CLI MCP server (24 tools, zero Node.js dependencies)",
   "homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli/tree/main/packages/claude-code-plugin",
diff --git a/packages/claude-code-plugin/plugins/switchbot/.claude-plugin/plugin.json b/packages/claude-code-plugin/plugins/switchbot/.claude-plugin/plugin.json
@@ -1,9 +1,13 @@
 {
   "name": "switchbot",
+  "displayName": "SwitchBot",
   "version": "0.1.0",
   "description": "Control SwitchBot smart-home devices from Claude Code via MCP.",
   "author": {
     "name": "OpenWonderLabs"
   },
-  "homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli"
+  "repository": "https://github.com/OpenWonderLabs/switchbot-openapi-cli",
+  "homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli",
+  "license": "MIT",
+  "keywords": ["switchbot", "smart-home", "iot", "mcp"]
 }
diff --git a/packages/claude-code-plugin/plugins/switchbot/.mcp.json b/packages/claude-code-plugin/plugins/switchbot/.mcp.json
@@ -1,6 +1,8 @@
 {
-  "switchbot": {
-    "command": "switchbot",
-    "args": ["mcp", "serve", "--tools", "all"]
+  "mcpServers": {
+    "switchbot": {
+      "command": "switchbot",
+      "args": ["mcp", "serve", "--tools", "all"]
+    }
   }
 }
diff --git a/packages/codex-plugin/.agents/plugins/marketplace.json b/packages/codex-plugin/.agents/plugins/marketplace.json
@@ -1,10 +1,18 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "switchbot",
+  "interface": {
+    "displayName": "SwitchBot"
+  },
   "plugins": [
     {
       "name": "switchbot",
-      "source": "./plugins/switchbot"
+      "source": "./plugins/switchbot",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }
diff --git a/packages/codex-plugin/marketplace.json b/packages/codex-plugin/marketplace.json
@@ -1,9 +1,18 @@
 {
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "switchbot",
+  "interface": {
+    "displayName": "SwitchBot"
+  },
   "plugins": [
     {
       "name": "switchbot",
-      "source": "./plugins/switchbot"
+      "source": "./plugins/switchbot",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }
diff --git a/packages/codex-plugin/package.json b/packages/codex-plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/codex-plugin",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "SwitchBot Codex plugin — wires Codex to the SwitchBot CLI MCP server (24 tools, zero Node.js dependencies)",
   "homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli/tree/main/packages/codex-plugin",
diff --git a/packages/codex-plugin/plugins/switchbot/.codex-plugin/hooks.json b/packages/codex-plugin/plugins/switchbot/.codex-plugin/hooks.json
@@ -1,6 +1,6 @@
 {
   "onInstall": {
-    "command": "node",
-    "args": ["../../../bin/auth.js", "--hook"]
+    "command": "switchbot-codex-auth",
+    "args": ["--hook"]
   }
 }
diff --git a/packages/codex-plugin/tests/hooks.test.js b/packages/codex-plugin/tests/hooks.test.js
@@ -0,0 +1,32 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const pluginRoot = resolve(__dirname, '../plugins/switchbot');
+const pkgJson = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf8'));
+
+describe('hooks.json', () => {
+  const hooksPath = resolve(pluginRoot, '.codex-plugin/hooks.json');
+
+  it('exists on disk', () => {
+    assert.ok(existsSync(hooksPath), `hooks.json missing at ${hooksPath}`);
+  });
+
+  it('onInstall.command is switchbot-codex-auth (not a relative path)', () => {
+    const hooks = JSON.parse(readFileSync(hooksPath, 'utf8'));
+    const cmd = hooks?.onInstall?.command;
+    assert.equal(cmd, 'switchbot-codex-auth',
+      `onInstall.command must be the global binary "switchbot-codex-auth", got "${cmd}"`);
+  });
+
+  it('switchbot-codex-auth is declared in package.json#bin', () => {
+    const bin = pkgJson?.bin ?? {};
+    assert.ok(
+      Object.prototype.hasOwnProperty.call(bin, 'switchbot-codex-auth'),
+      'switchbot-codex-auth must be declared in package.json#bin so the hook command is on PATH after npm install -g'
+    );
+  });
+});
diff --git a/scripts/smoke-codex-git-sparse.mjs b/scripts/smoke-codex-git-sparse.mjs
@@ -41,27 +41,32 @@ try {
     runGit(['clone', '--no-checkout', '--branch', ref, repoRoot, stagingDir], { cwd: workDir });
   }
   runGit(['-C', stagingDir, 'sparse-checkout', 'init', '--cone'], { cwd: workDir });
-  runGit(['-C', stagingDir, 'sparse-checkout', 'set', '.claude-plugin', 'packages/codex-plugin'], { cwd: workDir });
+  runGit(['-C', stagingDir, 'sparse-checkout', 'set', '.claude-plugin', 'packages/codex-plugin', 'packages/claude-code-plugin'], { cwd: workDir });
   runGit(['-C', stagingDir, 'checkout', ref], { cwd: workDir });
 
+  // .claude-plugin/marketplace.json — Claude Code plugin marketplace entry point
   const rootMarketplacePath = path.join(stagingDir, '.claude-plugin', 'marketplace.json');
+  // packages/codex-plugin/.agents/plugins/marketplace.json — Codex Route B entry point
   const packageMarketplacePath = path.join(stagingDir, 'packages', 'codex-plugin', '.agents', 'plugins', 'marketplace.json');
   const pluginMcpPath = path.join(stagingDir, 'packages', 'codex-plugin', 'plugins', 'switchbot', '.mcp.json');
+  // packages/claude-code-plugin/plugins/switchbot — Claude Code plugin source
+  const claudeCodePluginJsonPath = path.join(stagingDir, 'packages', 'claude-code-plugin', 'plugins', 'switchbot', '.claude-plugin', 'plugin.json');
 
-  for (const requiredPath of [rootMarketplacePath, packageMarketplacePath, pluginMcpPath]) {
+  for (const requiredPath of [rootMarketplacePath, packageMarketplacePath, pluginMcpPath, claudeCodePluginJsonPath]) {
     if (!existsSync(requiredPath)) {
       throw new Error(`sparse checkout missing ${path.relative(stagingDir, requiredPath)}`);
     }
   }
 
+  // Root marketplace must point to the Claude Code plugin directory
   const rootMarketplace = readJson(rootMarketplacePath);
   if (rootMarketplace?.name !== 'switchbot') {
     throw new Error(`root marketplace name must be switchbot, got ${rootMarketplace?.name ?? '<missing>'}`);
   }
   const rootPlugin = rootMarketplace?.plugins?.find((plugin) => plugin?.name === 'switchbot');
-  if (rootPlugin?.source !== './packages/codex-plugin/plugins/switchbot') {
+  if (rootPlugin?.source !== './packages/claude-code-plugin/plugins/switchbot') {
     throw new Error(
-      `root marketplace switchbot source must be ./packages/codex-plugin/plugins/switchbot, got ${rootPlugin?.source ?? '<missing>'}`,
+      `root marketplace switchbot source must be ./packages/claude-code-plugin/plugins/switchbot, got ${rootPlugin?.source ?? '<missing>'}`,
     );
   }
 
@@ -74,7 +79,7 @@ try {
     throw new Error(`package marketplace switchbot source must be ./plugins/switchbot, got ${packagePlugin?.source ?? '<missing>'}`);
   }
 
-  console.log(`codex git sparse smoke ok: ref ${ref} exposes root and package marketplace manifests with switchbot sources`);
+  console.log(`codex git sparse smoke ok: ref ${ref} exposes Claude Code and Codex marketplace manifests with correct sources`);
 } finally {
   try {
     rmSync(workDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
diff --git a/src/commands/capabilities.ts b/src/commands/capabilities.ts
@@ -218,6 +218,7 @@ export const COMMAND_META: Record<string, CommandMeta> = {
   'codex doctor': READ_LOCAL,
   'codex repair': ACTION_LOCAL,
   'codex setup': ACTION_LOCAL,
+  'claude-code setup': ACTION_LOCAL,
   'uninstall': ACTION_LOCAL,
   'upgrade-check': READ_REMOTE,
   'webhook setup': ACTION_REMOTE,
diff --git a/src/commands/claude-code.ts b/src/commands/claude-code.ts
diff --git a/src/commands/codex.ts b/src/commands/codex.ts
diff --git a/src/install/claude-code-checks.ts b/src/install/claude-code-checks.ts
diff --git a/src/program-builder.ts b/src/program-builder.ts
diff --git a/tests/commands/claude-code.test.ts b/tests/commands/claude-code.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,14 +1,15 @@`
`1`	`1`	`{`
`2`	`2`	`"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",`
`3`	`3`	`"name": "switchbot",`
	`4`	`+ "owner": {`
	`5`	`+ "name": "OpenWonderLabs",`
	`6`	`+ "email": "developer@wondertechlabs.com"`
	`7`	`+ },`
`4`	`8`	`"plugins": [`
`5`	`9`	`{`
`6`	`10`	`"name": "switchbot",`
`7`		`- "source": "./packages/codex-plugin/plugins/switchbot",`
`8`		`- "policy": {`
`9`		`- "installation": "AVAILABLE",`
`10`		`- "authentication": "ON_INSTALL"`
`11`		`- },`
	`11`	`+ "source": "./packages/claude-code-plugin/plugins/switchbot",`
	`12`	`+ "description": "Control SwitchBot smart-home devices from Claude Code via MCP.",`
`12`	`13`	`"category": "Productivity"`
`13`	`14`	`}`
`14`	`15`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,17 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "switchbot",`
	`3`	`+ "interface": {`
	`4`	`+ "displayName": "SwitchBot"`
	`5`	`+ },`
`3`	`6`	`"plugins": [`
`4`	`7`	`{`
`5`	`8`	`"name": "switchbot",`
`6`		`- "source": "./packages/codex-plugin/plugins/switchbot"`
	`9`	`+ "source": "./packages/codex-plugin/plugins/switchbot",`
	`10`	`+ "policy": {`
	`11`	`+ "installation": "AVAILABLE",`
	`12`	`+ "authentication": "ON_INSTALL"`
	`13`	`+ },`
	`14`	`+ "category": "Productivity"`
`7`	`15`	`}`
`8`	`16`	`]`
`9`	`17`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@switchbot/openapi-cli",`
`3`		`- "version": "3.7.6",`
	`3`	`+ "version": "3.7.7",`
`4`	`4`	`"description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"switchbot",`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@`
`15`	`15`	`"name": "OpenWonderLabs"`
`16`	`16`	`},`
`17`	`17`	`"source": "./plugins/switchbot",`
`18`		`- "category": "productivity",`
	`18`	`+ "category": "Productivity",`
`19`	`19`	`"homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli"`
`20`	`20`	`}`
`21`	`21`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@switchbot/claude-code-plugin",`
`3`		`- "version": "0.1.1",`
	`3`	`+ "version": "0.1.2",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"description": "SwitchBot Claude Code plugin — wires Claude Code to the SwitchBot CLI MCP server (24 tools, zero Node.js dependencies)",`
`6`	`6`	`"homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli/tree/main/packages/claude-code-plugin",`