pi-keyboard 0.1.6 → 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frad LEE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,7 @@
 # pi-keyboard
 
+Lighting commands use `via-rgb`, which owns HID packet encoding.
+
 Dynamic VIA/QMK keyboard RGB lighting indicator reflecting Pi's internal states.
 
 Ambient physical awareness of what your AI coding agent is doing right on your mechanical keyboard:
@@ -27,6 +29,15 @@ Supports discrete control for keyboard lighting channels:
 - **Per-Key Matrix** (`matrix`): Keycap backlight (Channel 3 in VIA/QMK).
 - **Underglow / Side Strips** (`underglow`): Bottom and edge light strips (Channel 2 in VIA/QMK).
 
+## Shared Directory Session Registry
+
+Per-session glow records use pi-kit’s canonical directory identity, hashed into
+the registry directory name. Existing paths are resolved through `realpath`,
+while missing paths use their absolute path; this keeps slash-versus-hyphen
+project names separate. Reads, cleanup, and clean shutdown verify the stored
+`cwd` belongs to the requested directory. Older registry directory names are
+not migrated.
+
 ---
 
 ## Structure
@@ -37,7 +48,6 @@ keyboard/
 ├── src/
 │   ├── config.ts      — Keyboard config read/write helpers
 │   ├── driver.ts      — via-rgb binary resolution & CLI execution
-│   ├── protocol.ts    — VIA RAW HID packet building
 │   ├── state-machine.ts — State transitions and LED apply logic
 │   ├── global-sessions.ts — Per-cwd session glow record registry
 │   ├── types.ts       — KeyboardState, KeyboardZone, KeyboardConfig
@@ -49,14 +59,6 @@ keyboard/
 
 ## Installation
 
-Install from this monorepo or local path:
-
-```bash
-pi install ~/Developer/FradSer/pi-packages/packages/keyboard
-```
-
-Published on npm:
-
 ```bash
 pi install npm:pi-keyboard
 ```
@@ -118,3 +120,7 @@ Settings are saved in `~/.pi/agent/keyboard.json`:
   "saveToEeprom": false
 }
 ```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # pi-keyboard
 
-基于 VIA/QMK 协议的 Pi 键盘 RGB 状态指示灯插件。
+基于 VIA/QMK 协议的 Pi 键盘 RGB 状态指示灯插件。通过 `via-rgb` 执行灯光命令，由该程序负责 HID 数据包编码。
 
 通过机械键盘的 RGB 灯光，实时提供 AI Coding Agent 运行状态的环境感知：
 
@@ -27,6 +27,13 @@
 - **按键背光矩阵** (`matrix`)：仅控制键帽背光（QMK 通道 3）。
 - **侧边底灯** (`underglow`)：仅控制外壳侧边/底部灯带（QMK 通道 2）。
 
+## 共享目录会话注册表
+
+每个会话的灯光记录使用 pi-kit 的规范目录身份，并将其哈希为注册表目录名。
+已存在的路径通过 `realpath` 解析，不存在的路径使用绝对路径，因此仅以斜杠和连字符
+区分的项目不会碰撞。读取、清理和正常退出删除记录前都会核验记录中的 `cwd` 属于请求的
+目录；旧目录名不会迁移。
+
 ---
 
 ## 安装方式

package/features/keyboard.feature

@@ -104,6 +104,12 @@ Feature: Pi Keyboard Lighting Indicator
     And it no longer contributes to the green unread light
     And a live unread session still keeps its green light
 
+  Scenario: Keyboard glow records verify canonical directory ownership
+    Given a registry file is stored under one directory key with another canonical cwd
+    When keyboard cleanup or global state evaluation runs
+    Then the foreign record is ignored
+    And clean shutdown does not delete the foreign record
+
   Scenario: Target lighting zone selection
     Given the user configures the target zone
     When the zone is set to "matrix"
@@ -128,6 +134,30 @@ Feature: Pi Keyboard Lighting Indicator
     When a state transition occurs
     Then the driver fails gracefully without throwing unhandled exceptions or crashing Pi
 
+  Scenario: Missing via-rgb executable reports a failed hardware update
+    Given the configured via-rgb executable does not exist
+    When a keyboard state transition is queued
+    Then the transition result reports failure
+    And the driver does not report a successful HID write
+
+  Scenario: Non-zero via-rgb exit reports a failed hardware update
+    Given the configured via-rgb executable exits with a non-zero status
+    When a keyboard state transition is queued
+    Then the transition result reports failure
+    And its error identifies the failed command
+
+  Scenario: Hardware updates remain serial and recover after a failed command
+    Given two keyboard state transitions are queued
+    And the first transition fails
+    When the queue drains
+    Then the second transition starts only after the first settles
+    And the second transition result is reported independently
+
+  Scenario: Homebrew via-rgb candidate uses the executable path
+    Given via-rgb is installed under the Homebrew prefix
+    When the driver resolves standard executable candidates
+    Then it checks "/opt/homebrew/bin/via-rgb" as one candidate
+
   Scenario: /keyboard command allows manual state testing and toggle
     Given the /keyboard command is executed
     When the user toggles lighting to "off"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-keyboard",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Dynamic VIA/QMK keyboard RGB lighting indicator reflecting Pi states (idle, thinking, unread, need-approval, error)",
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",
@@ -38,6 +38,6 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.4.2"
+    "@fradser/pi-kit": "0.5.1"
   }
 }

package/src/driver.ts

@@ -13,16 +13,14 @@ import {
 const execFileAsync = promisify(execFile);
 
 let activeBlinkTimer: NodeJS.Timeout | null = null;
-let commandQueue: Promise<void> = Promise.resolve();
+let commandQueue: Promise<HardwareApplyResult> | undefined;
 
 export function resolveCliPath(customPath?: string): string {
-  if (customPath && existsSync(customPath)) {
-    return customPath;
-  }
+  if (customPath) return customPath;
 
   const standardPaths = [
     join(homedir(), ".local", "bin", "via-rgb"),
-    "/opt/homebrew/bin", "via-rgb",
+    join("/opt/homebrew/bin", "via-rgb"),
     "/usr/local/bin/via-rgb",
   ];
 
@@ -122,16 +120,9 @@ export async function applyKeyboardState(
   };
 
   // Queue to ensure strictly ordered HID writes
-  commandQueue = commandQueue.then(
-    async () => {
-      await task();
-    },
-    async () => {
-      await task();
-    },
-  );
-  await commandQueue;
-  return { success: true, state, zone: config.zone };
+  const queuedTask = (commandQueue ?? Promise.resolve()).then(task, task);
+  commandQueue = queuedTask;
+  return await queuedTask;
 }
 
 function startSoftwareStrobe(

package/src/global-sessions.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { getDirectorySessionKey, isSameDirectory } from "@fradser/pi-kit";
 import type { KeyboardState } from "./types";
 
 export interface SessionGlowRecord {
@@ -20,10 +21,8 @@ export function getRegistryDir(): string {
   return path.join(os.homedir(), ".pi", "agent", "directory-sessions");
 }
 
-export function getSessionFileKey(cwd: string): string {
-  const normalized = path.resolve(cwd || process.cwd());
-  return `--${normalized.replace(/^[/\\\\]/, "").replace(/[/\\\\:]/g, "-")}--`;
-}
+/** Shared directory-session key used by every registry writer and reader. */
+export const getSessionFileKey = getDirectorySessionKey;
 
 export function getDirectoryRegistryPath(cwd: string): string {
   return path.join(getRegistryDir(), getSessionFileKey(cwd));
@@ -78,6 +77,8 @@ export function removeSessionGlowState(cwd: string, sessionId: string): void {
   try {
     const filePath = path.join(getDirectoryRegistryPath(cwd), `${sessionId}.json`);
     if (fs.existsSync(filePath)) {
+      const record = JSON.parse(fs.readFileSync(filePath, "utf-8")) as { cwd?: unknown };
+      if (typeof record.cwd !== "string" || !isSameDirectory(record.cwd, cwd)) return;
       fs.unlinkSync(filePath);
     }
   } catch {
@@ -119,6 +120,9 @@ export function pruneOrphanedGlowStates(): number {
           const content = fs.readFileSync(filePath, "utf-8");
           const record = JSON.parse(content) as SessionGlowRecord;
           if (!record || typeof record !== "object" || typeof record.pid !== "number") continue;
+          if (typeof record.cwd !== "string" || dirEntry.name !== getDirectorySessionKey(record.cwd)) {
+            continue;
+          }
           if (!isProcessAlive(record.pid)) {
             try {
               fs.unlinkSync(filePath);
@@ -189,6 +193,9 @@ export function evaluateGlobalLightingState(
             const record = JSON.parse(content) as SessionGlowRecord;
 
             if (!record || typeof record !== "object") continue;
+            if (typeof record.cwd !== "string" || dirEntry.name !== getDirectorySessionKey(record.cwd)) {
+              continue;
+            }
 
             // Prune dead process IDs
             if (!isProcessAlive(record.pid)) {

package/src/protocol.ts

@@ -1,62 +0,0 @@
-import type { KeyboardZone } from "./types";
-
-export const VIA_RAW_USAGE_PAGE = 0xff60;
-export const VIA_RAW_USAGE = 0x0061;
-
-export const CMD_GET_PROTOCOL_VERSION = 0x01;
-export const CMD_CUSTOM_SET_VALUE = 0x07;
-export const CMD_CUSTOM_GET_VALUE = 0x08;
-export const CMD_CUSTOM_SAVE = 0x09;
-
-export const CH_RGBLIGHT = 2; // Zone 1: Side strip / Underglow
-export const CH_RGB_MATRIX = 3; // Zone 2: Per-key RGB Matrix
-
-export const VAL_BRIGHTNESS = 1;
-export const VAL_EFFECT = 2;
-export const VAL_EFFECT_SPEED = 3;
-export const VAL_COLOR = 4;
-
-export function resolveChannels(zone: KeyboardZone): number[] {
-  switch (zone) {
-    case "underglow":
-      return [CH_RGBLIGHT];
-    case "matrix":
-      return [CH_RGB_MATRIX];
-    case "all":
-    default:
-      return [CH_RGBLIGHT, CH_RGB_MATRIX];
-  }
-}
-
-export function buildPacket(payload: number[]): Uint8Array {
-  const packet = new Uint8Array(32);
-  for (let i = 0; i < payload.length && i < 32; i++) {
-    packet[i] = payload[i];
-  }
-  return packet;
-}
-
-export function buildSetBrightnessPacket(channel: number, brightness: number): Uint8Array {
-  const val = Math.max(0, Math.min(255, Math.round(brightness)));
-  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_BRIGHTNESS, val]);
-}
-
-export function buildSetEffectPacket(channel: number, effect: number): Uint8Array {
-  const val = Math.max(0, Math.min(255, Math.round(effect)));
-  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_EFFECT, val]);
-}
-
-export function buildSetSpeedPacket(channel: number, speed: number): Uint8Array {
-  const val = Math.max(0, Math.min(255, Math.round(speed)));
-  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_EFFECT_SPEED, val]);
-}
-
-export function buildSetColorPacket(channel: number, hue: number, sat: number): Uint8Array {
-  const h = Math.max(0, Math.min(255, Math.round(hue)));
-  const s = Math.max(0, Math.min(255, Math.round(sat)));
-  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_COLOR, h, s]);
-}
-
-export function buildSavePacket(channel: number): Uint8Array {
-  return buildPacket([CMD_CUSTOM_SAVE, channel]);
-}