Migrate to the native toolchain

Author: Luligu

.claude/rules/matterbridge/matterbridge.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: 'How to create MatterbridgeEndpoint instances, register them in Matterbridge plugins, and use the single-class devices exported by the package v. 1.0.0'
+description: 'How to create MatterbridgeEndpoint instances, register them in Matterbridge plugins, and use the single-class devices exported by the package v. 1.0.1'
 ---
 
 # Matterbridge Endpoint Guide
@@ -49,24 +49,18 @@ Recommended pattern:
 ```ts
 const device = new MatterbridgeEndpoint([contactSensor, powerSource], { id: 'EntryDoor' })
   .createDefaultIdentifyClusterServer()
-  .createDefaultBridgedDeviceBasicInformationClusterServer(
-    'Entry Door',
-    'ENTRY-DOOR-001',
-    0xfff1,
-    'Matterbridge',
-    'Entry Door Sensor',
-  )
+  .createDefaultBridgedDeviceBasicInformationClusterServer('Entry Door', 'ENTRY-DOOR-001', 0xfff1, 'Matterbridge', 'Entry Door Sensor')
   .createDefaultBooleanStateClusterServer(false)
   .createDefaultPowerSourceReplaceableBatteryClusterServer(75)
-  .addRequiredClusterServers();
+  .addRequiredClusters();
 ```
 
 Rules that matter:
 
 - `definition` can be a single device type or an array of device types.
 - Use multiple device types when the endpoint needs more than one role, for example `[contactSensor, powerSource]`.
 - Call one of the Basic Information helpers before `registerDevice()`. Without `deviceName`, `serialNumber`, and `uniqueId`, registration fails.
-- Call `addRequiredClusterServers()` at the end of the chain so any required clusters that you did not explicitly create are added automatically.
+- Call `addRequiredClusters()` at the end of the chain so any required clusters (server or client) that you did not explicitly create are added automatically.
 - Use `addOptionalClusterServers()` only when you really want the optional clusters defined by the selected device type(s).
 
 ## MatterbridgeEndpointOptions
@@ -116,7 +110,7 @@ Important behavior:
 
 In plugin code, prefer `this.registerDevice(device)` instead of calling Matterbridge internals directly.
 
-DynamicPlatform bridged endpoint:
+DynamicPlatform bridged device:
 
 ```ts
 import { MatterbridgeDynamicPlatform, MatterbridgeEndpoint, onOffLight } from 'matterbridge';
@@ -130,13 +124,7 @@ class ExamplePlatform extends MatterbridgeDynamicPlatform {
     await this.ready;
 
     const device = new MatterbridgeEndpoint(onOffLight, { id: 'OnOffLightPlugin' })
-      .createDefaultBridgedDeviceBasicInformationClusterServer(
-        'Kitchen Light',
-        'LIGHT-001',
-        0xfff1,
-        'Matterbridge',
-        'Matterbridge OnOffLight',
-      )
+      .createDefaultBridgedDeviceBasicInformationClusterServer('Kitchen Light', 'LIGHT-001', 0xfff1, 'Matterbridge', 'Matterbridge OnOffLight')
       .addRequiredClusterServers();
 
     await this.registerDevice(device);
@@ -158,14 +146,7 @@ class ExamplePlatform extends MatterbridgeAccessoryPlatform {
     await this.ready;
 
     const device = new MatterbridgeEndpoint(temperatureSensor, { id: 'TemperatureSensorPlugin' })
-      .createDefaultBasicInformationClusterServer(
-        'Temperature Sensor',
-        'TEMP-001',
-        0xfff1,
-        'Matterbridge',
-        0x8000,
-        'Matterbridge Temperature Sensor',
-      )
+      .createDefaultBasicInformationClusterServer('Temperature Sensor', 'TEMP-001', 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Temperature Sensor')
       .addRequiredClusterServers();
 
     await this.registerDevice(device);
@@ -177,14 +158,7 @@ Standalone Matter device from a plugin:
 
 ```ts
 const device = new MatterbridgeEndpoint(pressureSensor, { id: 'ServerNodeDevice', mode: 'server' })
-  .createDefaultBasicInformationClusterServer(
-    'Server Node Device',
-    'SERVER-001',
-    0xfff1,
-    'Matterbridge',
-    0x8000,
-    'Matterbridge Server Node Device',
-  )
+  .createDefaultBasicInformationClusterServer('Server Node Device', 'SERVER-001', 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Server Node Device')
   .addRequiredClusterServers();
 
 await this.registerDevice(device);
@@ -194,14 +168,7 @@ Native Matter endpoint on the server node:
 
 ```ts
 const device = new MatterbridgeEndpoint(pressureSensor, { id: 'MatterNodeDevice', mode: 'matter' })
-  .createDefaultBasicInformationClusterServer(
-    'Matter Node Device',
-    'MATTER-001',
-    0xfff1,
-    'Matterbridge',
-    0x8000,
-    'Matterbridge Matter Node Device',
-  )
+  .createDefaultBasicInformationClusterServer('Matter Node Device', 'MATTER-001', 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Matter Node Device')
   .addRequiredClusterServers();
 
 await this.registerDevice(device);
@@ -227,6 +194,7 @@ Common helpers on the endpoint instance:
 - `subscribeAttribute(cluster, attribute, listener)`
 - `addRequiredClusterServers()`
 - `addOptionalClusterServers()`
+- `addRequiredClusters()`
 
 Example:
 
@@ -241,6 +209,8 @@ Cluster references can be passed in several ways:
 - cluster id
 - cluster name string such as `'OnOff'`
 
+Behavior type and cluster type are preferred because they are type-safe and avoid typos.
+
 Using the cluster name string is useful in plugins because it avoids importing every cluster type.
 
 ## When to use a raw endpoint vs a single-class device

.claude/rules/testing/unit-tests.instructions.md

@@ -5,23 +5,24 @@ paths:
   - '**/src/**/*.spec.ts'
   - '**/test/**/*.ts'
   - '**/vitest/**/*.ts'
+  - '**/buntest/**/*.ts'
 ---
 
 # Testing Standards for Unit Tests
 
 ## 1. Test Framework
 
-- Use Jest (with ts-jest) or Vitest as the testing framework for all unit tests.
 - Jest is available in the repository when the file `jest.config.js` exists.
 - Vitest is available in the repository when the file `vite.config.ts` exists.
-- Avoid using both Jest and Vitest in the same project to prevent conflicts. When both are available, prefer Vitest for new tests and consider migrating existing Jest tests to Vitest over time.
-- Jest tests live adjacent to the code being tested with a `.test.ts` suffix or in `test` folders. Follow the existing convention in the repository for test file placement.
-- Vitest tests live adjacent to the code being tested with a `.test.ts` suffix or in `vitest` folders. Follow the existing convention in the repository for test file placement.
+- Bun test is available in the repository when the file `bunfig.toml` exists.
+- Jest tests live in `test` folders. Follow the existing convention in the repository for test file placement.
+- Vitest tests live in `vitest` folders. Follow the existing convention in the repository for test file placement.
+- Bun test tests live in `buntest` folders. Follow the existing convention in the repository for test file placement.
 - Ensure that tests are written in TypeScript and follow the ESM module format.
 
 ## 2. Test Structure
 
-- Organize tests in file name `*.test.ts` adjacent to the code being tested.
+- Organize tests in file name `*.test.ts` in the `test`, `vitest`, or `buntest` folders.
 - Use `describe` blocks to group related tests and `test` blocks for individual test cases.
 
 ## 3. Test Naming
@@ -47,12 +48,13 @@ paths:
 - Run the relevant full test unit from start to finish rather than assuming isolated single-test execution is reliable.
 - If only one test framework is installed, use `npm run test -- yourTest.test.ts` or `npm run test:coverage -- yourTest.test.ts` when the touched area can be validated by running the full relevant test file.
 - When both Jest and Vitest are installed, use `npm run test -- yourTest.test.ts` for Jest or `npm run test:vitest -- yourTest.test.ts` for Vitest.
+- When Bun test is installed, use `bun test yourTest.test.ts`.
 - Use the existing `tasks.json` test tasks for areas that require grouped test files, custom coverage targets, or custom ignore-pattern handling.
 - Avoid running all tests unnecessarily to save time and tokens.
 
 ## 8. Test Assertions
 
-- Use appropriate Jest or Vitest matchers for assertions (e.g., `toBe`, `toEqual`, `toThrow`).
+- Use appropriate Jest, Vitest, or Bun test matchers for assertions (e.g., `toBe`, `toEqual`, `toThrow`).
 - Ensure that assertions are clear and directly related to the behavior being tested.
 
 ## 9. Performance

.claude/settings.json

@@ -1,10 +1,13 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "Claude settings v. 1.0.3",
   "permissions": {
     "deny": [
-      "Read(./.env)",
-      "Read(./.env.*)",
-      "Read(./**/secrets/**)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/.env)",
+      "Read(**/.env.*)",
+      "Read(**/secrets/**)",
       "Bash(git pull:*)",
       "Bash(git merge:*)",
       "Bash(git push:*)",
@@ -16,12 +19,36 @@
       "Bash(git branch -d:*)",
       "Bash(git tag -d:*)",
       "Bash(git reflog expire:*)",
-      "Bash(git reflog delete:*)",
-      "Bash(git push --delete:*)",
-      "Bash(git push --force:*)",
-      "Bash(git push -f:*)"
+      "Bash(git reflog delete:*)"
     ],
-    "ask": ["Bash(git commit:*)", "Bash(npm install:*)", "Bash(npm i:*)"],
-    "allow": ["Bash(npm run typecheck)", "Bash(npm run build)", "Bash(npm run test:*)", "Bash(npm run lint)", "Bash(npm run format)"]
+    "ask": [
+      "Bash(git commit:*)",
+      "Bash(npm install:*)",
+      "Bash(npm i:*)",
+      "Bash(npm uninstall:*)",
+      "Bash(bun install:*)",
+      "Bash(bun i:*)",
+      "Bash(bun uninstall:*)",
+      "Bash(bun add:*)",
+      "Bash(bun remove:*)"
+    ],
+    "allow": [
+      "Bash(npm run typecheck)",
+      "Bash(npm run build)",
+      "Bash(npm run test:*)",
+      "Bash(npm run lint)",
+      "Bash(npm run format)",
+      "Bash(bun test)",
+      "Bash(npx vitest:*)",
+      "Bash(vitest:*)",
+      "Bash(npx oxfmt:*)",
+      "Bash(oxfmt:*)",
+      "Bash(npx oxlint:*)",
+      "Bash(oxlint:*)",
+      "Bash(npx tsc:*)",
+      "Bash(tsc:*)",
+      "Bash(npx tsgo:*)",
+      "Bash(tsgo:*)"
+    ]
   }
 }

.codex/config.toml

@@ -0,0 +1,29 @@
+# Codex config v. 1.0.1
+
+approval_policy = "on-request"
+approvals_reviewer = "user"
+default_permissions = "matterbridge_safe"
+web_search = "live"
+
+[shell_environment_policy]
+inherit = "core"
+
+[windows]
+sandbox = "elevated"
+
+[permissions.matterbridge_safe.network]
+enabled = false
+
+[permissions.matterbridge_safe]
+description = "Workspace access with sensitive files denied and network disabled."
+extends = ":workspace"
+
+[permissions.matterbridge_safe.filesystem]
+glob_scan_max_depth = 4
+
+[permissions.matterbridge_safe.filesystem.":workspace_roots"]
+".env" = "deny"
+".env.*" = "deny"
+"**/.env" = "deny"
+"**/.env.*" = "deny"
+"**/secrets/**" = "deny"

.codex/rules/default.rules

@@ -0,0 +1,43 @@
+# Codex rules v. 1.0.1
+
+# Git mutations
+prefix_rule(pattern = ["git", "pull"], decision = "forbidden", justification = "Do not change local refs without explicit manual control.")
+prefix_rule(pattern = ["git", "merge"], decision = "forbidden", justification = "Do not merge automatically.")
+prefix_rule(pattern = ["git", "push"], decision = "forbidden", justification = "Do not push automatically.")
+prefix_rule(pattern = ["git", "rebase"], decision = "forbidden", justification = "Do not rewrite branch history automatically.")
+prefix_rule(pattern = ["git", "commit"], decision = "forbidden", justification = "Do not create commits automatically.")
+prefix_rule(pattern = ["git", "commit", "--amend"], decision = "forbidden", justification = "Do not amend commits automatically.")
+prefix_rule(pattern = ["git", "reset", "--hard"], decision = "forbidden", justification = "Destructive reset is blocked.")
+prefix_rule(pattern = ["git", "filter-branch"], decision = "forbidden", justification = "History rewriting is blocked.")
+prefix_rule(pattern = ["git", "branch", "-D"], decision = "forbidden", justification = "Branch deletion is blocked.")
+prefix_rule(pattern = ["git", "branch", "-d"], decision = "forbidden", justification = "Branch deletion is blocked.")
+prefix_rule(pattern = ["git", "tag", "-d"], decision = "forbidden", justification = "Tag deletion is blocked.")
+prefix_rule(pattern = ["git", "reflog", "expire"], decision = "forbidden", justification = "Reflog mutation is blocked.")
+prefix_rule(pattern = ["git", "reflog", "delete"], decision = "forbidden", justification = "Reflog mutation is blocked.")
+
+# Dependency installs
+prefix_rule(pattern = ["npm", "install"], decision = "prompt", justification = "Ask before installing dependencies.")
+prefix_rule(pattern = ["npm", "i"], decision = "prompt", justification = "Ask before installing dependencies.")
+prefix_rule(pattern = ["npm", "uninstall"], decision = "prompt", justification = "Ask before uninstalling dependencies.")
+prefix_rule(pattern = ["bun", "install"], decision = "prompt", justification = "Ask before installing dependencies.")
+prefix_rule(pattern = ["bun", "i"], decision = "prompt", justification = "Ask before installing dependencies.")
+prefix_rule(pattern = ["bun", "uninstall"], decision = "prompt", justification = "Ask before uninstalling dependencies.")
+prefix_rule(pattern = ["bun", "add"], decision = "prompt", justification = "Ask before installing dependencies.")
+prefix_rule(pattern = ["bun", "remove"], decision = "prompt", justification = "Ask before uninstalling dependencies.")
+
+# Validation scripts
+prefix_rule(pattern = ["npm", "run", "typecheck"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "build"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "test"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "test:watch"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "test:verbose"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "test:coverage"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "lint"], decision = "allow")
+prefix_rule(pattern = ["npm", "run", "format"], decision = "allow")
+prefix_rule(pattern = ["bun", "test"], decision = "allow")
+
+# External network and containers
+prefix_rule(pattern = ["curl"], decision = "prompt", justification = "Ask before external network fetches.")
+prefix_rule(pattern = ["Invoke-WebRequest"], decision = "prompt", justification = "Ask before external network fetches.")
+prefix_rule(pattern = ["docker", "pull"], decision = "prompt", justification = "Ask before downloading Docker images.")
+prefix_rule(pattern = ["docker", "run"], decision = "prompt", justification = "Ask before running Docker containers.")

.devcontainer/devcontainer.json

@@ -1,4 +1,4 @@
-// .devcontainer/devcontainer.json v. 1.0.2
+// .devcontainer/devcontainer.json v. 1.0.4
 
 // This file defines the development container configuration for a Matterbridge Plugin.
 
@@ -47,7 +47,9 @@ Dev containers have networking limitations depending on the host OS and Docker s
     "source=${localWorkspaceFolderBasename}-plugins,target=/home/node/Matterbridge,type=volume",
     "source=${localWorkspaceFolderBasename}-storage,target=/home/node/.matterbridge,type=volume",
     "source=${localWorkspaceFolderBasename}-cert,target=/home/node/.mattercert,type=volume",
-    "source=matterbridge,target=/matterbridge,type=volume"
+    "source=matterbridge,target=/matterbridge,type=volume",
+    "source=claude-code,target=/home/node/.claude,type=volume",
+    "source=codex,target=/home/node/.codex,type=volume"
   ],
   // Create the matterbridge Docker network if it doesn't exist, then pull the base image (runs on the HOST before the container starts).
   "initializeCommand": "(docker network inspect matterbridge || docker network create matterbridge) && docker pull mcr.microsoft.com/devcontainers/javascript-node:24-trixie",
@@ -72,41 +74,40 @@ Dev containers have networking limitations depending on the host OS and Docker s
       "extensions": [
         "typescriptteam.native-preview",
         "oxc.oxc-vscode",
+        "vitest.explorer",
+        "firsttris.vscode-jest-runner",
         "ms-azuretools.vscode-containers",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode",
         "anthropic.claude-code",
         "github.copilot-chat",
         "github.vscode-github-actions",
-        "github.vscode-pull-request-github"
+        "github.vscode-pull-request-github",
+        "openai.chatgpt"
       ],
       // Settings for the VS Code environment
       "settings": {
         // Default .vscode/settings.json
-        "eslint.enable": true,
-        "prettier.enable": true,
-        "oxc.enable": false,
+        "eslint.enable": false,
+        "prettier.enable": false,
+        "oxc.enable": true,
         "js/ts.experimental.useTsgo": true,
         "js/ts.tsdk.promptToUseWorkspaceVersion": false,
+        "jestrunner.enableESM": true,
+        "jestrunner.codeLens": ["run", "watch", "coverage", "debug"],
         "terminal.integrated.scrollback": 10000,
         "editor.tabSize": 2,
         "editor.rulers": [180],
-        "editor.formatOnSave": true,
-        "editor.defaultFormatter": "dbaeumer.vscode-eslint",
-        "[javascript]": { "editor.defaultFormatter": "dbaeumer.vscode-eslint" },
-        "[typescript]": { "editor.defaultFormatter": "dbaeumer.vscode-eslint" },
-        "[json]": { "editor.defaultFormatter": "dbaeumer.vscode-eslint" },
-        "[jsonc]": { "editor.defaultFormatter": "dbaeumer.vscode-eslint" },
-        "[markdown]": { "editor.defaultFormatter": "dbaeumer.vscode-eslint" },
+        "editor.formatOnSave": false,
+        "editor.defaultFormatter": "oxc.oxc-vscode",
+        "[javascript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+        "[typescript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+        "[json]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+        "[jsonc]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+        "[markdown]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+        "editor.formatOnSaveMode": "file",
         "editor.codeActionsOnSave": {
-          "source.fixAll.eslint": "explicit"
+          "source.format.oxc": "always",
+          "source.fixAll.oxc": "always"
         },
-        "eslint.format.enable": true,
-        "eslint.options": {
-          "cache": true,
-          "cacheLocation": ".cache/.eslintcache"
-        },
-        "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact", "json", "jsonc", "markdown"],
         "diffEditor.ignoreTrimWhitespace": false,
         "files.eol": "\n",
         "files.insertFinalNewline": true,
@@ -126,6 +127,7 @@ Dev containers have networking limitations depending on the host OS and Docker s
         },
         "git.autofetch": true,
         "git.autoRepositoryDetection": false,
+        // VS Code's Copilot Chat extension settings
         "chat.useCustomizationsInParentRepositories": false,
         "chat.useClaudeMdFile": true,
         "chat.instructionsFilesLocations": {