claude-code-hub 1.34.0 → 1.35.0

package/lib/keymap.js

@@ -17,7 +17,7 @@ const PATTERN_ACTIONS = new Set(['hub.appByNumber']);
 const MODS = ['ctrl', 'alt', 'shift', 'meta'];
 
 // A combo name as the SDK's comboOf() gives it (protocol section 8), with one modifier at least.
-const COMBO_RE = /^(?=(?:ctrl|alt|shift|meta)\+)(?:ctrl\+)?(?:alt\+)?(?:shift\+)?(?:meta\+)?(?:[a-z1-9,]|[A-Z][A-Za-z0-9]+)$/;
+const COMBO_RE = /^(?=(?:ctrl|alt|shift|meta)\+)(?:ctrl\+)?(?:alt\+)?(?:shift\+)?(?:meta\+)?(?:[a-z0-9,.;'`/\\=\-[\]]|[A-Z][A-Za-z0-9]+)$/;
 
 // "Ctrl+Alt+O" → "ctrl+alt+o", the form comboOf() gives. Null when the text cannot name a combo.
 function normalizeCombo(text) {

package/lib/onboarding.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pluginChecker } = require('./plugin-status');
+
+const ONBOARDING = ['done', 'skipped'];
+const SETTLED = new Set(['ok', 'disabled']);
+
+function canonical(p) {
+  try {
+    return fs.realpathSync.native(p);
+  } catch {
+    return null;
+  }
+}
+
+// Claude config dirs in the home folder that the hub does not list yet: a `.claude*` folder with a
+// settings.json or a projects folder, so a cache or a backup folder is left out.
+function findConfigDirs({ home, known, hubDir }) {
+  let entries;
+  try {
+    entries = fs.readdirSync(home, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const skip = new Set([...known, hubDir].map((d) => canonical(d) ?? d));
+  return entries
+    .filter((e) => e.isDirectory() && e.name.startsWith('.claude'))
+    .map((e) => path.join(home, e.name))
+    .filter((d) => fs.existsSync(path.join(d, 'settings.json')) || fs.existsSync(path.join(d, 'projects')))
+    .map((d) => canonical(d))
+    .filter((d) => d && !skip.has(d))
+    .sort();
+}
+
+// `plugins` is [{id, name, bundled, install, args}]: args are the hub command-line arguments that install it.
+function dirPlugins(configDir, plugins) {
+  const check = pluginChecker(configDir);
+  return plugins.map((p) => {
+    const { state, installed, bundled } = check(p);
+    return { id: p.id, name: p.name, state, installed, bundled };
+  });
+}
+
+function pluginsToInstall(configDir, plugins) {
+  const check = pluginChecker(configDir);
+  return plugins.filter((p) => !SETTLED.has(check(p).state));
+}
+
+function setupStatus({ tray, configDirs, activeConfigDir, candidates, plugins }) {
+  const dirs = configDirs.map((d) => {
+    const list = dirPlugins(d, plugins);
+    return { path: d, active: d === activeConfigDir, plugins: list, pending: list.some((p) => !SETTLED.has(p.state)) };
+  });
+  return { tray, dirs, candidates, pluginsDone: dirs.every((d) => !d.pending) };
+}
+
+module.exports = { ONBOARDING, findConfigDirs, pluginsToInstall, setupStatus };

package/lib/settings.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { isObject, selectApps, validSettingValue } = require('./apps');
+const { userKeys } = require('./keymap');
 
 const CONFIG_DIR_SWITCH = ['palette', 'swap'];
 const DEFAULT_POOL_SIZE = 3;
@@ -72,9 +73,15 @@ function withSettings(entry, schema, patch) {
 // `saved` is config.json as on disk. Returns the new config, or {error}. Only the keys the
 // patch names change; an app entry keeps its other fields (port, path, source). `schemas` maps an
 // app id to the settings list of its manifest.
-function applySettings(saved, patch, base, schemas = {}) {
+function applySettings(saved, patch, base, schemas = {}, apps = []) {
   if (!patch || typeof patch !== 'object') return { error: 'body must be an object' };
   const next = { ...saved };
+  if (patch.keys !== undefined) {
+    const { keys, lines } = userKeys(patch.keys, apps);
+    if (lines.length) return { error: lines.join('; ') };
+    if (Object.keys(keys).length) next.keys = keys;
+    else delete next.keys;
+  }
   if (patch.configDirSwitch !== undefined) {
     if (!CONFIG_DIR_SWITCH.includes(patch.configDirSwitch))
       return { error: `configDirSwitch must be one of ${CONFIG_DIR_SWITCH.join(', ')}` };

package/lib/tray.js

@@ -1,16 +1,19 @@
 'use strict';
 
-const { execFileSync, spawn } = require('node:child_process');
+const { execFile, execFileSync, spawn } = require('node:child_process');
 const crypto = require('node:crypto');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { promisify } = require('node:util');
 const { version } = require('../package.json');
 const { liveHub } = require('./hub-record');
 
 const TRAY_SRC = path.join(__dirname, '..', 'tray');
 const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
 const LAUNCH_AGENTS = path.join(os.homedir(), 'Library', 'LaunchAgents');
+// The hub page asks for the tray state, so the checks must not block the hub's event loop.
+const run = promisify(execFile);
 
 function dirHash(hubDir) {
   return crypto.createHash('sha1').update(path.resolve(hubDir).toLowerCase()).digest('hex').slice(0, 8);
@@ -68,13 +71,13 @@ function windows(hubDir) {
   return {
     area: 'notification area',
     prepare: () => ({ runValue: value }),
-    trayAlive(pid) {
-      const out = execFileSync('tasklist', ['/fi', `PID eq ${pid}`, '/fo', 'csv', '/nh'], { encoding: 'utf8' });
-      return out.toLowerCase().startsWith('"powershell.exe"');
+    async trayAlive(pid) {
+      const { stdout } = await run('tasklist', ['/fi', `PID eq ${pid}`, '/fo', 'csv', '/nh'], { windowsHide: true });
+      return stdout.toLowerCase().startsWith('"powershell.exe"');
     },
-    autostartName() {
+    async autostartName() {
       try {
-        execFileSync('reg', ['query', RUN_KEY, '/v', value], { stdio: 'ignore' });
+        await run('reg', ['query', RUN_KEY, '/v', value], { windowsHide: true });
         return value;
       } catch {
         return null;
@@ -106,14 +109,14 @@ function macos(hubDir, launchAgentsDir) {
       fs.writeFileSync(trayPlist, launchAgentPlist({ label, script: launcher }));
       return { launchAgent: plist, path: process.env.PATH };
     },
-    trayAlive(pid) {
+    async trayAlive(pid) {
       try {
-        return execFileSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' }).includes('hub-tray.js');
+        return (await run('ps', ['-p', String(pid), '-o', 'command='])).stdout.includes('hub-tray.js');
       } catch {
         return false;
       }
     },
-    autostartName: () => (fs.existsSync(plist) ? label : null),
+    autostartName: async () => (fs.existsSync(plist) ? label : null),
     addAutostart() {
       fs.mkdirSync(launchAgentsDir, { recursive: true });
       fs.copyFileSync(trayPlist, plist);
@@ -144,12 +147,29 @@ function copyTray(plat, { hubDir, port, appId, defaultPort }) {
   return dest;
 }
 
-async function printStatus(plat, { hubDir, configDir }) {
-  const autostart = plat.autostartName();
-  let trayPid = null;
+async function trayPid(plat, hubDir) {
+  let pid = null;
   try {
-    trayPid = Number.parseInt(fs.readFileSync(path.join(hubDir, 'tray.pid'), 'utf8'), 10);
+    pid = Number.parseInt(fs.readFileSync(path.join(hubDir, 'tray.pid'), 'utf8'), 10);
   } catch {}
+  return Number.isInteger(pid) && (await plat.trayAlive(pid)) ? pid : null;
+}
+
+function platformOf(platform, hubDir, launchAgentsDir) {
+  if (platform === 'darwin') return macos(hubDir, launchAgentsDir);
+  return platform === 'win32' ? windows(hubDir) : null;
+}
+
+// {supported, autostart, running} for the hub page's setup checklist.
+async function trayState({ hubDir, platform = process.platform, launchAgentsDir = LAUNCH_AGENTS }) {
+  const plat = platformOf(platform, hubDir, launchAgentsDir);
+  if (!plat) return { supported: false, autostart: false, running: false };
+  const [autostart, pid] = await Promise.all([plat.autostartName(), trayPid(plat, hubDir)]);
+  return { supported: true, autostart: !!autostart, running: pid !== null };
+}
+
+async function printStatus(plat, { hubDir, configDir }) {
+  const [autostart, pid] = await Promise.all([plat.autostartName(), trayPid(plat, hubDir)]);
   let hub = null;
   try {
     hub = await liveHub(hubDir, fs.readFileSync(path.join(hubDir, 'token'), 'utf8').trim());
@@ -157,16 +177,16 @@ async function printStatus(plat, { hubDir, configDir }) {
   console.log(`  Hub dir: ${hubDir}`);
   console.log(`  Config dir: ${configDir}`);
   console.log(`  Autostart: ${autostart ? `on (${autostart})` : 'off'}`);
-  console.log(`  Tray: ${Number.isInteger(trayPid) && plat.trayAlive(trayPid) ? `running (pid ${trayPid})` : 'not running'}`);
+  console.log(`  Tray: ${pid !== null ? `running (pid ${pid})` : 'not running'}`);
   console.log(`  Hub: ${hub ? `running on port ${hub.port} (pid ${hub.pid})` : 'stopped'}`);
 }
 
 async function runTrayCommand({ flag, platform = process.platform, launchAgentsDir = LAUNCH_AGENTS, ...opts }) {
-  if (platform !== 'win32' && platform !== 'darwin') {
+  const plat = platformOf(platform, opts.hubDir, launchAgentsDir);
+  if (!plat) {
     console.error(`  ${flag} works only on Windows and macOS.`);
     return false;
   }
-  const plat = platform === 'darwin' ? macos(opts.hubDir, launchAgentsDir) : windows(opts.hubDir);
   if (flag === '--tray-status') {
     await printStatus(plat, opts);
     return true;
@@ -185,4 +205,4 @@ async function runTrayCommand({ flag, platform = process.platform, launchAgentsD
   return true;
 }
 
-module.exports = { runTrayCommand, runValue, launchAgentLabel, launchAgentPlist, appConfig };
+module.exports = { runTrayCommand, trayState, runValue, launchAgentLabel, launchAgentPlist, appConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -46,10 +46,10 @@
   },
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
-    "claude-code-cost": "1.6.1",
-    "claude-code-kanban": "7.31.0",
-    "claude-code-marketplace": "1.7.2",
-    "claude-code-memory-explorer": "1.3.5",
+    "claude-code-cost": "1.6.2",
+    "claude-code-kanban": "7.32.0",
+    "claude-code-marketplace": "1.7.3",
+    "claude-code-memory-explorer": "1.3.6",
     "express": "^4.21.0",
     "open": "^10.1.0"
   },

package/packages/claude-hub-sdk/src/client.js

@@ -111,6 +111,7 @@
       const tokenWaiters = new Set();
       const themesFns = new Set();
       const settingsFns = new Set();
+      const keysFns = new Set();
       const queued = [];
       // Topic → payload: the latest publish before welcome.
       const outbox = new Map();
@@ -253,6 +254,12 @@
           case 'hub:settings':
             if (welcome) setSettings(m.settings);
             return;
+          case 'hub:keys':
+            if (!welcome) return;
+            welcome.keys = comboMap(m.keys);
+            forward = strings(m.forward);
+            for (const fn of keysFns) fn();
+            return;
         }
       }
 
@@ -472,6 +479,12 @@
         forwards,
         // The combos forwards() matches, for a frame that tests keys with ClaudeHub.comboOf on its own.
         forwardCombos: () => (forward ? [...forward] : []),
+        // Calls fn after the user changes the hub's keys, so a page that copied forwardCombos() or
+        // shows keyLabel() can read them again.
+        onKeys(fn) {
+          keysFns.add(fn);
+          return () => keysFns.delete(fn);
+        },
         // The keys of a hub action for a help row, in this system's names. A list of actions shares one
         // row: ['Ctrl', 'Alt', '←/→']. [] when no key runs them; null before welcome, standalone, or
         // for an action the hub did not list.

package/packages/claude-hub-sdk/src/keys.js

@@ -9,19 +9,62 @@ var ClaudeHubKeys = (() => {
   // Modifiers in ctrl, alt, shift, meta order, joined by '+' to the key. macOS composes
   // Option+<key> into a character (Option+1 is '¡', Option+P is 'π') and holding Control does not
   // undo it, so e.key alone cannot name these presses there. e.code is the physical key, which is
-  // wrong for non-US layouts, hence only as a fallback. No fallback under AltGraph: Chromium sets it
-  // when AltGr types a character, and that press is text. Takes a real KeyboardEvent or a forwarded
-  // {key, code} payload; a payload without code degrades to key. A payload needs no AltGraph: the
-  // SDK forwards only a press whose key already names a bound combo.
-  // Self-contained on purpose: cck puts its source text into a sandboxed frame.
+  // wrong for non-US layouts, hence only as a fallback. A letter or punctuation key falls back to its
+  // US character only when e.key is not ASCII (a non-Latin layout, or Option on macOS), so AZERTY's
+  // ',' on the M key stays ','. The digit row always falls back, so AZERTY's '&' key is 1, as Windows
+  // and VS Code treat it. No fallback under AltGraph: Chromium sets it when AltGr types a character, and that
+  // press is text. Takes a real KeyboardEvent or a forwarded {key, code} payload; a payload without
+  // code degrades to key. A payload needs no AltGraph: the SDK forwards only a press whose key
+  // already names a bound combo.
+  // Self-contained on purpose, the table too: cck puts its source text into a sandboxed frame.
+  // codeOf() lists the same keys the other way round.
   function comboOf(e) {
-    const lower = typeof e.key === 'string' ? e.key.toLowerCase() : '';
-    const m = !e.getModifierState?.('AltGraph') && /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
-    const key = /^[a-z1-9]$/.test(lower) ? lower : m ? m[1].toLowerCase() : e.key === ' ' ? 'Space' : e.key;
+    const raw = typeof e.key === 'string' ? e.key : '';
+    const lower = raw.toLowerCase();
+    const code = e.getModifierState?.('AltGraph') ? '' : e.code || '';
+    const latin = !/[^\x20-\x7e]/.test(raw);
+    const digit = /^Digit([0-9])$/.exec(code)?.[1];
+    const us =
+      !latin &&
+      (/^Key([A-Z])$/.exec(code)?.[1].toLowerCase() ||
+        {
+          Minus: '-',
+          Equal: '=',
+          BracketLeft: '[',
+          BracketRight: ']',
+          Backslash: '\\',
+          Semicolon: ';',
+          Quote: "'",
+          Backquote: '`',
+          Comma: ',',
+          Period: '.',
+          Slash: '/',
+        }[code]);
+    const key = /^[a-z0-9]$/.test(lower) ? lower : digit || us || (e.key === ' ' ? 'Space' : e.key);
     const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
     return [...mods, key].filter(Boolean).join('+');
   }
 
+  // The physical key (e.code) that types a combo's key on a US layout, or null for a named key.
+  function codeOf(key) {
+    if (/^[a-z]$/.test(key)) return `Key${key.toUpperCase()}`;
+    if (/^[0-9]$/.test(key)) return `Digit${key}`;
+    const codes = {
+      '-': 'Minus',
+      '=': 'Equal',
+      '[': 'BracketLeft',
+      ']': 'BracketRight',
+      '\\': 'Backslash',
+      ';': 'Semicolon',
+      "'": 'Quote',
+      '`': 'Backquote',
+      ',': 'Comma',
+      '.': 'Period',
+      '/': 'Slash',
+    };
+    return codes[key] ?? null;
+  }
+
   // The keys of a combo as a help row shows them: ['Ctrl', 'Alt', 'P'], or ['⌃', '⌥', 'P'] on macOS.
   // The {n} of a numbered combo reads 1…9.
   function keyParts(combo, mac) {
@@ -46,7 +89,7 @@ var ClaudeHubKeys = (() => {
     ].filter(Boolean);
   }
 
-  return { comboOf, keyParts, keySigs };
+  return { comboOf, codeOf, keyParts, keySigs };
 })();
 
 if (typeof module === 'object' && module.exports) module.exports = ClaudeHubKeys;

package/packages/claude-hub-sdk/src/stub.js

@@ -39,6 +39,7 @@
         can: (action) => !!standaloneFn(action),
         forwards: () => false,
         forwardCombos: () => [],
+        onKeys: () => off,
         keyLabel: () => null,
         voiceCommands: () => [],
         closeGuard() {},

package/plugin/plugins/claude-code-hub/skills/hub-builder/references/keys.md

@@ -2,11 +2,13 @@
 
 The hub's own keys (switch tools, open the palettes) live in the `keys` block of `<hub-dir>/config.json` (`--hub-dir`, else `CLAUDE_HUB_DIR`, else `~/.claude-hub`). Each tool's own keys are outside it. Page: `reference/shortcuts/#change-the-keys`.
 
+The user can change them without you: hub settings (`Ctrl+,`), **Keyboard** page, **Customize…**. The window applies a change at once, with no restart. Point the user there first. Edit the file only when the user asks you to.
+
 ## Steps
 
 1. Map each key the user asks for to an action in [Actions](#actions), and check its combo against [Rules](#rules). When a combo breaks a rule, tell the user why and offer one that passes.
 2. Read `config.json` and merge the entries into its `keys` block. Every other field stays byte for byte: the hub owns `configDirs`, `activeConfigDir` and `apps`.
-3. Restart the hub: it reads `keys` once, at startup. When the tray runs it, the user picks Quit in the tray menu and starts the hub again.
+3. Restart the hub: it reads the file's `keys` once, at startup. When the tray runs it, the user picks Quit in the tray menu and starts the hub again.
 4. Read the startup output, or `<hub-dir>/hub.log` when the tray started the hub. The hub logs each entry it drops as `<config.json path>: keys "<action>": … It keeps its default`. The reason is one of: not a combo, not a combo that ends in `+{n}`, `<combo> is kept by <app>`, `<combo> is already set for "<action>"`. An id that is not an action logs `keys "<id>" is not a hub action, ignored`.
 5. Read `GET http://localhost:<port>/api/config?token=<token>` (the token is in `<hub-dir>/token`).
 
@@ -42,7 +44,7 @@ Ctrl+Alt+O opens the project palette, Ctrl+Alt+H and Ctrl+Alt+L move between too
 
 ## Rules
 
-- **Form.** One or more of `ctrl`, `alt`, `shift`, `meta`, then one key, joined by `+`. The key is a letter, a digit 1 to 9, `,`, or a `KeyboardEvent.key` name (`ArrowUp`, `F2`, `PageDown`). On macOS `alt` is Option and `meta` is Command. Modifiers and letters take any case and order (`"Alt+Ctrl+O"` reads as `ctrl+alt+o`); a key name keeps its case (`PageDown`).
+- **Form.** One or more of `ctrl`, `alt`, `shift`, `meta`, then one key, joined by `+`. The key is a letter, a digit, one of `` , . ; ' ` / \ = - [ ] ``, or a `KeyboardEvent.key` name (`ArrowUp`, `F2`, `PageDown`). On macOS `alt` is Option and `meta` is Command. Modifiers and letters take any case and order (`"Alt+Ctrl+O"` reads as `ctrl+alt+o`); a key name keeps its case (`PageDown`).
 - **`{n}`.** `hub.appByNumber` ends in `+{n}`, and the hub binds it for 1 to 9. It is the only action with `{n}`.
 - **`null`** leaves the action with no key.
 - **Taking a default.** A combo that is another action's default moves to the new action, and the other action has no key until it gets one: `"hub.nextApp": "ctrl+alt+a"` leaves the app launcher with no key. Say so to the user.