claude-code-hub 0.42.0 → 1.0.1

package/README.md

@@ -116,9 +116,14 @@ By default the hub runs all four tools. To turn a tool off or change the tab ord
 - The ids are `kanban`, `marketplace`, `cost` and `memory`.
 - The tools you list come first, in list order. The tools you do not list follow in the default order.
 - A tool with `"enabled": false` does not start and gets no tab. Links from other tools to it do nothing.
+- `"port": 4543` sets the tool's port. See [Ports](https://nikiforovall.blog/claude-code-hub/reference/configuration/#ports) for the order and the busy-port fallback.
 - With Kanban off, the embedded terminal is off, and the project palette has no project list. You can still type a path.
 - Restart the hub after you edit the file.
 
+## Run a second hub
+
+Give the second hub its own folder for the config file and token with `--hub-dir <path>` or `CLAUDE_HUB_DIR`. See [Run a second hub](https://nikiforovall.blog/claude-code-hub/reference/configuration/#run-a-second-hub).
+
 ## Embedded terminal
 
 Under the hub, Kanban has an embedded terminal, on by default, so you can start or resume Claude Code sessions from the board. While a terminal is attached, the hub asks before it closes the window, because <kbd>Ctrl</kbd>+<kbd>W</kbd> meant for the terminal would close it.
@@ -145,6 +150,7 @@ The hub has no visible UI of its own. Use these shortcuts:
 | <kbd>Alt</kbd>+<kbd>4</kbd> | Memory Diagnoser |
 | <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd> | Project palette: set the project for all tools |
 | <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>W</kbd> | Config-dir palette: switch, add, or remove a config dir |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd> | App launcher: switch to a tool, or restart it with <kbd>Ctrl</kbd>+<kbd>R</kbd> |
 
 <kbd>Alt</kbd>+<kbd>1</kbd> to <kbd>Alt</kbd>+<kbd>4</kbd> follow the tab order, so they change when you [choose the tools](#choose-the-tools).
 

package/lib/actions.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const PARAM_TYPES = new Set(['string', 'string?']);
+const MODES = new Set(['url', 'message']);
+
+function actionError(name, spec) {
+  if (name.startsWith('hub.')) return 'uses the hub. prefix';
+  if (typeof spec !== 'object' || spec === null) return 'is not an object';
+  if (spec.url !== undefined && typeof spec.url !== 'string') return 'has a url that is not a string';
+  if (spec.url?.includes('#')) return 'has a # in its url';
+  if (spec.mode !== undefined && !MODES.has(spec.mode)) return `has an unknown mode ${JSON.stringify(spec.mode)}`;
+  const params = spec.params ?? {};
+  if (typeof params !== 'object' || Object.values(params).some((t) => !PARAM_TYPES.has(t))) {
+    return 'has a param type that is not "string" or "string?"';
+  }
+  return null;
+}
+
+// Protocol §7: the first app in tab order that declares an action handles it.
+function actionTable(apps, log = console.log) {
+  const table = {};
+  for (const app of apps) {
+    const handles = app.actions?.handles ?? {};
+    if (typeof handles !== 'object' || Array.isArray(handles)) {
+      log(`${app.id}: actions.handles is not an object, skipped`);
+      continue;
+    }
+    for (const [name, spec] of Object.entries(handles)) {
+      const err = actionError(name, spec);
+      if (err) log(`${app.id}: action "${name}" ${err}, skipped`);
+      else if (!Object.hasOwn(table, name)) {
+        table[name] = { app: app.id, params: spec.params ?? {}, url: spec.url, mode: spec.mode ?? 'url' };
+      }
+    }
+  }
+  return table;
+}
+
+module.exports = { actionTable };

package/lib/apps.js

@@ -1,23 +1,150 @@
 'use strict';
 
-// Built-in apps in their default tab order.
+const fs = require('node:fs');
+const path = require('node:path');
+const { isContained } = require('./contain');
+
+// Built-in apps in their default tab order. The rest of each app comes from its manifest.
 const APPS = [
-  { id: 'kanban', dir: 'cck', pkg: 'claude-code-kanban', name: 'Kanban', icon: 'columns', port: 3541 },
-  { id: 'marketplace', dir: 'marketplace', pkg: 'claude-code-marketplace', name: 'Marketplace', icon: 'store', port: 3542 },
-  { id: 'cost', dir: 'cost', pkg: 'claude-code-cost', name: 'Cost', icon: 'dollar-sign', port: 3543 },
-  { id: 'memory', dir: 'memory', pkg: 'claude-code-memory-explorer', name: 'Memory Diagnoser', icon: 'database', port: 3544 },
+  { id: 'kanban', dir: 'cck', pkg: 'claude-code-kanban' },
+  { id: 'marketplace', dir: 'marketplace', pkg: 'claude-code-marketplace' },
+  { id: 'cost', dir: 'cost', pkg: 'claude-code-cost' },
+  { id: 'memory', dir: 'memory', pkg: 'claude-code-memory-explorer' },
 ];
 
+const ID_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const HUB_ROOT = path.join(__dirname, '..');
+
+const validPort = (p) => Number.isInteger(p) && p > 0 && p < 65536;
+
 // `entries` is the hand-edited `apps` list in config.json. Listed apps come first in list order and
 // unlisted ones follow in default order, so an app added in a later release shows up without an edit.
-function selectApps(entries = []) {
+// An entry with a `path` runs the app in that folder: a fork in place of a built-in app, or a new app.
+// A relative `path` is resolved against `base`, the folder of config.json.
+function selectApps(entries = [], base = process.cwd()) {
   const listed = entries.filter((e) => typeof e?.id === 'string');
-  const byId = (id) => APPS.find((a) => a.id === id);
+  const entryOf = (id) => listed.find((e) => e.id === id);
+  const pathOf = (id) => {
+    const p = entryOf(id)?.path;
+    return typeof p === 'string' && p ? path.resolve(base, p) : undefined;
+  };
+  const byId = (id) => APPS.find((a) => a.id === id) ?? (pathOf(id) ? { id } : undefined);
   const unknown = listed.map((e) => e.id).filter((id) => !byId(id));
   const off = new Set(listed.filter((e) => e.enabled === false).map((e) => e.id));
   const order = new Set([...listed.map((e) => e.id), ...APPS.map((a) => a.id)]);
-  const apps = [...order].map(byId).filter((a) => a && !off.has(a.id));
+  const apps = [...order]
+    .map(byId)
+    .filter((a) => a && !off.has(a.id))
+    .map((a) => ({ ...a, port: entryOf(a.id)?.port, path: pathOf(a.id) }));
   return { apps, unknown };
 }
 
-module.exports = { selectApps };
+// Two enabled apps that claim the same capability, action or default port. The first in tab order
+// wins each one, so a fork listed next to the app it replaces loses silently without these lines.
+function conflicts(apps) {
+  const lines = [];
+  const seen = new Map();
+  const claim = (kind, key, id) => {
+    const first = seen.get(`${kind}\n${key}`);
+    if (first === undefined) seen.set(`${kind}\n${key}`, id);
+    else lines.push(`${id} and ${first} both declare ${kind} "${key}"; ${first} has it. Disable one of them.`);
+  };
+  for (const a of apps) {
+    for (const cap of Object.keys(a.provides ?? {})) claim('capability', cap, a.id);
+    for (const name of Object.keys(a.actions?.handles ?? {})) claim('action', name, a.id);
+    if (a.port) claim('port', String(a.port), a.id);
+  }
+  return lines;
+}
+
+function manifestError(m, id, root) {
+  if (m?.manifest !== 1) return `unknown manifest version ${JSON.stringify(m?.manifest)}`;
+  if (typeof m.id !== 'string' || !ID_RE.test(m.id)) return `id ${JSON.stringify(m.id)} does not match ${ID_RE}`;
+  if (m.id !== id) return `id "${m.id}" is not "${id}"`;
+  if (typeof m.run?.entry !== 'string') return 'run.entry is missing';
+  const entry = path.resolve(root, m.run.entry);
+  if (entry === path.resolve(root) || !isContained(entry, root)) return 'run.entry is outside the app directory';
+  return providesError(m.provides) ?? publishesError(m.publishes);
+}
+
+const TOPIC_RE = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+// The hub publishes these itself.
+const HUB_TOPICS = new Set(['theme.changed', 'project.changed']);
+
+function publishesError(publishes) {
+  if (publishes === undefined) return null;
+  if (!Array.isArray(publishes)) return 'publishes is not an array';
+  for (const t of publishes) {
+    if (typeof t !== 'string' || !TOPIC_RE.test(t)) return `publishes topic ${JSON.stringify(t)} does not match ${TOPIC_RE}`;
+    if (HUB_TOPICS.has(t) || t.startsWith('hub.')) return `publishes topic "${t}" is the hub's`;
+  }
+  return null;
+}
+
+// The hub fetches each path from the provider's own server.
+const CAPABILITY_PATHS = { projects: 'path', terminal: 'liveWork' };
+
+function providesError(provides) {
+  if (provides === undefined) return null;
+  if (typeof provides !== 'object' || provides === null || Array.isArray(provides)) return 'provides is not an object';
+  for (const [cap, key] of Object.entries(CAPABILITY_PATHS)) {
+    if (provides[cap] === undefined) continue;
+    const p = provides[cap]?.[key];
+    if (typeof p !== 'string' || !p.startsWith('/')) return `provides.${cap}.${key} is not a path`;
+  }
+  return null;
+}
+
+function readManifest(root, id) {
+  const m = JSON.parse(fs.readFileSync(path.join(root, 'hub-app.json'), 'utf8'));
+  const err = manifestError(m, id, root);
+  if (err) throw new Error(err);
+  return m;
+}
+
+// The entry's path, else the submodule when it is checked out, else the installed package.
+function appRoot(app, hubRoot, resolve) {
+  if (app.path) return app.path;
+  const local = path.join(hubRoot, app.dir);
+  if (fs.existsSync(path.join(local, 'package.json'))) return local;
+  return path.dirname(resolve(`${app.pkg}/package.json`));
+}
+
+// The --<id>-port flag, then the config entry's port. Undefined when neither is set and valid.
+function userPort(app, flagPort, log) {
+  const sources = [
+    [`--${app.id}-port`, flagPort == null ? undefined : Number(flagPort)],
+    [`"port" of "${app.id}" in config.json`, app.port],
+  ];
+  for (const [source, port] of sources) {
+    if (port === undefined) continue;
+    if (validPort(port)) return port;
+    log(`${source} is not a valid port, ignored`);
+  }
+}
+
+// Null, with a log line, when the app's hub-app.json is missing or not valid.
+function loadApp(app, { flagPort, hubRoot = HUB_ROOT, resolve = require.resolve, log = console.log } = {}) {
+  const root = appRoot(app, hubRoot, resolve);
+  let manifest;
+  try {
+    manifest = readManifest(root, app.id);
+  } catch (e) {
+    const reason = e.code === 'ENOENT' ? 'not found' : e.message;
+    log(`${path.join(root, 'hub-app.json')}: ${reason}. ${app.id} is skipped`);
+    return null;
+  }
+  return {
+    id: app.id,
+    entry: path.join(root, manifest.run.entry),
+    port: userPort(app, flagPort, log) ?? manifest.run.defaultPort ?? 0,
+    name: manifest.name ?? app.id,
+    icon: manifest.icon,
+    loading: manifest.loading ?? {},
+    actions: manifest.actions ?? {},
+    provides: manifest.provides ?? {},
+    publishes: manifest.publishes ?? [],
+  };
+}
+
+module.exports = { APPS, selectApps, loadApp, manifestError, conflicts };

package/lib/contain.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// Path containment check.
+//
+// The obvious implementation — `child.startsWith(root)` — is wrong twice over:
+// it accepts a sibling directory that merely shares a prefix ("/plugins/foo-evil"
+// passes a check for "/plugins/foo"), and it is blind to symlinks, `..`, casing
+// and Windows 8.3 short names. This uses path.relative instead, and canonicalises
+// both sides first.
+//
+// CANONICAL COPY: scripts/security-lib/contain.js in the claude-code-hub repo.
+// Run scripts/sync-security-lib.sh after editing.
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const IS_WIN = process.platform === 'win32';
+
+// realpath the deepest existing ancestor, then re-append the non-existent tail,
+// so a not-yet-created file under a symlinked directory still canonicalises.
+function realpathDeepest(target) {
+  let cur = target;
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native(cur);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return target; // reached the volume root, nothing resolvable
+      tail.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function canonical(target, deepest) {
+  let out = path.resolve(target);
+  if (deepest) out = realpathDeepest(out);
+  else { try { out = fs.realpathSync.native(out); } catch { /* may not exist yet */ } }
+  // realpathSync.native has already expanded 8.3 short names (PROGRA~1) and fixed
+  // the casing of the existing portion; lowercase covers the rest.
+  return IS_WIN ? out.toLowerCase() : out;
+}
+
+function beneath(canonicalChild, root) {
+  const rel = path.relative(canonical(root, false), canonicalChild);
+  // '' means child === root. An absolute rel means a different drive or UNC share,
+  // which path.relative signals by giving up — reject those.
+  if (rel === '') return true;
+  if (path.isAbsolute(rel)) return false;
+  return rel !== '..' && !rel.startsWith(`..${path.sep}`);
+}
+
+/**
+ * True iff `child` is `root` itself or lies beneath it.
+ * @param {string} child
+ * @param {string} root
+ */
+function isContained(child, root) {
+  if (typeof child !== 'string' || typeof root !== 'string' || !child || !root) return false;
+  return beneath(canonical(child, true), root);
+}
+
+/**
+ * True iff `child` is contained by any of `roots`. Canonicalises the child once
+ * instead of once per root — callers testing a single path against several roots
+ * were paying that walk repeatedly.
+ * @param {string} child
+ * @param {string[]} roots
+ */
+function isContainedAny(child, roots) {
+  if (typeof child !== 'string' || !child || !Array.isArray(roots)) return false;
+  const c = canonical(child, true);
+  return roots.some((r) => typeof r === 'string' && r && beneath(c, r));
+}
+
+module.exports = { isContained, isContainedAny, realpathDeepest };

package/lib/install.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PLUGIN_SRC = path.join(__dirname, '..', 'plugin');
+const MARKETPLACE = 'claude-code-hub';
+const PLUGIN_ID = `claude-code-hub@${MARKETPLACE}`;
+
+// Claude Code keeps .claude.json beside ~/.claude when CLAUDE_CONFIG_DIR is unset but inside the
+// dir when it is set, so the default dir must stay unset rather than be spelled out.
+function claudeEnv(configDir) {
+  const isDefault = path.resolve(configDir) === path.resolve(os.homedir(), '.claude');
+  return isDefault ? process.env : { ...process.env, CLAUDE_CONFIG_DIR: configDir };
+}
+
+// `idempotent` when the output names an ok pattern, on exit 0 too: some commands report "already" and succeed.
+function run(cmd, env, okPatterns = []) {
+  const matches = (text) => okPatterns.some((p) => text.toLowerCase().includes(p));
+  try {
+    const output = execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env }).trim();
+    return { ok: true, idempotent: matches(output), output };
+  } catch (e) {
+    const error = e.stderr?.trim() || e.stdout?.trim() || e.message;
+    if (matches(error)) return { ok: true, idempotent: true, output: '' };
+    return { ok: false, error };
+  }
+}
+
+// Deletes files but never directories: on Windows a running Claude Code process holds handles on
+// the registered marketplace dirs, so removing one fails EPERM and leaves the copy half gone.
+function clearFiles(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const target = path.join(dir, entry.name);
+    if (entry.isDirectory()) clearFiles(target);
+    else fs.rmSync(target, { force: true });
+  }
+}
+
+function report(label, result, idempotentText) {
+  if (result.ok) console.log(`  ${label}: ${result.idempotent ? idempotentText : 'done'}`);
+  else console.log(`  ${label}: failed\n    ${result.error.split('\n').join('\n    ')}`);
+  return result.ok;
+}
+
+// One copy of the plugin in the hub dir; each config dir registers that copy as a marketplace.
+function runInstall({ hubDir, configDir }) {
+  const dest = path.join(hubDir, 'plugin');
+  const env = claudeEnv(configDir);
+  console.log(`\n  claude-code-hub plugin install\n  Config dir: ${configDir}\n  Plugin copy: ${dest}\n`);
+
+  if (!run('claude --version', env).ok) {
+    console.log('  claude CLI not found. Install Claude Code first.');
+    return false;
+  }
+
+  clearFiles(dest);
+  fs.cpSync(PLUGIN_SRC, dest, { recursive: true });
+  console.log('  Copy plugin: done');
+
+  let ok = report('Register marketplace', run(`claude plugin marketplace add "${dest}"`, env, ['already']), 'already registered');
+  // Claude caches the marketplace manifest, so a re-copied plugin stays invisible until refreshed.
+  ok = report('Refresh marketplace', run(`claude plugin marketplace update ${MARKETPLACE}`, env)) && ok;
+
+  const install = run(`claude plugin install ${PLUGIN_ID}`, env, ['already installed']);
+  ok = report('Install plugin', install, 'already installed') && ok;
+  // `install` exits 0 on a plugin that is present and keeps the cached old version; `update` loads the new copy.
+  if (install.idempotent) {
+    ok = report('Update plugin', run(`claude plugin update ${PLUGIN_ID}`, env, ['already at the latest']), 'already at the latest version') && ok;
+  }
+
+  console.log(ok ? '\n  Done. Start a new Claude Code session to load the hub-builder skill.\n' : '\n  Install incomplete, see the errors above.\n');
+  return ok;
+}
+
+// Keeps the plugin copy in the hub dir, because other config dirs can still point at it.
+function runUninstall({ configDir }) {
+  const env = claudeEnv(configDir);
+  console.log(`\n  claude-code-hub plugin uninstall\n  Config dir: ${configDir}\n`);
+  let ok = report('Remove plugin', run(`claude plugin uninstall ${PLUGIN_ID}`, env, ['not found', 'not installed']), 'not installed');
+  ok = report('Remove marketplace', run(`claude plugin marketplace remove ${MARKETPLACE}`, env, ['not found', 'not configured']), 'not registered') && ok;
+  console.log(ok ? '\n  Done.\n' : '\n  Uninstall incomplete, see the errors above.\n');
+  return ok;
+}
+
+module.exports = { runInstall, runUninstall, claudeEnv };

package/lib/kill-child.js

@@ -0,0 +1,32 @@
+'use strict';
+const { spawn: nodeSpawn } = require('node:child_process');
+
+const KILL_GRACE_MS = 3000;
+
+const exited = (child) => child.exitCode !== null || child.signalCode !== null;
+
+// POSIX: SIGTERM lets an app run its exit handlers (cck removes its server.json and ends its
+// terminals), but a handler on a frozen event loop never runs, so SIGKILL follows. Windows has no
+// SIGTERM for a Node child: taskkill /f /t ends it and the processes it started.
+// Resolves when the child has exited, or after graceMs (with SIGKILL sent on POSIX).
+function killChild(child, { platform = process.platform, spawn = nodeSpawn, graceMs = KILL_GRACE_MS } = {}) {
+  if (exited(child)) return Promise.resolve();
+  const done = new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      if (platform !== 'win32' && !exited(child)) child.kill('SIGKILL');
+      resolve();
+    }, graceMs);
+    timer.unref();
+    child.once('exit', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+  if (child.hubKilled) return done;
+  child.hubKilled = true;
+  if (platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/f', '/t'], { stdio: 'ignore' });
+  else child.kill('SIGTERM');
+  return done;
+}
+
+module.exports = { killChild, KILL_GRACE_MS };

package/lib/net-guard.js

@@ -36,6 +36,7 @@ const PORT_RE = /^[0-9]{1,5}$/;
 // The port is validated but not compared — the listen(0) fallbacks make the real
 // port dynamic, so only the host is allowlisted.
 const validPort = (p) => PORT_RE.test(p) && Number(p) >= 1 && Number(p) <= 65535;
+const KEEP_ALIVE_MS = 65000;
 
 function isLoopbackAddress(host) {
   if (!host) return false;
@@ -249,6 +250,10 @@ function createNetGuard(config = {}) {
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
     const makeServer = (handler) => {
       const s = http.createServer(serverOpts, handler);
+      // Node's 5 s default closes idle sockets that the hub proxy and the browser would reuse, and a
+      // fresh loopback connect is the one that some Windows network filters drop. The hub's agent
+      // drops its idle sockets before this, so it never reuses one the server is closing.
+      s.keepAliveTimeout = KEEP_ALIVE_MS;
       if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
       return s;
     };
@@ -281,4 +286,4 @@ function createNetGuard(config = {}) {
   return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
-module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };
+module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress, KEEP_ALIVE_MS };

package/lib/ping.js

@@ -0,0 +1,23 @@
+'use strict';
+
+let seq = 0;
+
+// Resolves true when the child answers hub:ping over its IPC channel within timeoutMs. The channel
+// does not use TCP, so a loopback connect failure does not stop the answer.
+function ping(child, timeoutMs) {
+  if (!child?.connected) return Promise.resolve(false);
+  const id = ++seq;
+  return new Promise((resolve) => {
+    const done = (ok) => {
+      clearTimeout(timer);
+      child.off('message', onMessage);
+      resolve(ok);
+    };
+    const onMessage = (m) => m?.type === 'hub:pong' && m.id === id && done(true);
+    const timer = setTimeout(() => done(false), timeoutMs);
+    child.on('message', onMessage);
+    child.send({ type: 'hub:ping', id }, (err) => err && done(false));
+  });
+}
+
+module.exports = { ping };

package/lib/themes.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const THEMES_FILE = path.join(__dirname, 'themes.json');
+
+const readThemes = (file = THEMES_FILE) => JSON.parse(fs.readFileSync(file, 'utf8'));
+
+const hexToRgb = (hex) => {
+  const n = parseInt(hex.slice(1), 16);
+  return `${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}`;
+};
+
+const glow = (color, mode) =>
+  /^#[0-9a-f]{6}$/i.test(color)
+    ? `rgba(${hexToRgb(color)}, ${mode === 'dark' ? '0.55' : '0.5'})`
+    : `color-mix(in srgb, ${color} ${mode === 'dark' ? '55%' : '50%'}, transparent)`;
+
+// Palette role → shared CSS variable. --accent-glow is mechanical (rgba of the accent), mirroring
+// how each app's :root derives it from --accent.
+const coreVars = (p, mode) => ({
+  '--accent': p.ember,
+  '--accent-text': p.emberGlow,
+  '--accent-dim': p.emberDim,
+  '--accent-glow': glow(p.ember, mode),
+  '--bg-deep': p.field,
+  '--bg-surface': p.surface,
+  '--bg-elevated': p.elevated,
+  '--bg-hover': p.hover,
+  '--border': p.border,
+  '--text-primary': p.ink1,
+  '--text-secondary': p.ink2,
+  '--text-tertiary': p.ink3,
+  '--text-muted': p.inkMuted,
+  ...(p.sidebar && { '--sidebar-bg': p.sidebar }),
+  ...(p.sidebarItem && { '--sidebar-item-bg': p.sidebarItem }),
+});
+
+const swatch = (p) => ({ bg: p.surface, accent: p.ember, ink: p.ink1, border: p.border });
+
+const modes = (t, fn) => ({ dark: fn(t.dark, 'dark'), light: fn(t.light, 'light') });
+
+const MODES = ['dark', 'light'];
+const ROLES = ['ember', 'emberGlow', 'emberDim', 'field', 'surface', 'elevated', 'hover', 'border', 'ink1', 'ink2', 'ink3', 'inkMuted'];
+const OPTIONAL_ROLES = ['sidebar', 'sidebarItem'];
+const THEME_ID = /^[a-z0-9-]{1,32}$/;
+// The SDK writes these values into inline styles and a style sheet, so no url(), quotes, semicolons or nested parens.
+const COLOR = /^(#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|(rgba?|hsla?|oklch)\([\w\s.,%/+-]*\))$/i;
+
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+// Why a user theme cannot be used, or null. `builtins` maps id → built-in theme.
+function themeProblem(e, builtins, seen) {
+  if (!isObject(e)) return 'not an object';
+  if (typeof e.id !== 'string' || !THEME_ID.test(e.id)) return 'id must match ^[a-z0-9-]{1,32}$';
+  if (seen.has(e.id)) return 'an earlier theme in the file has this id';
+  if (e.label !== undefined && typeof e.label !== 'string') return 'label must be a string';
+  if (e.extends !== undefined) {
+    if (builtins.has(e.id)) return 'a built-in id cannot take extends';
+    if (!builtins.has(e.extends)) return `extends names no built-in theme: ${e.extends}`;
+  }
+  const based = builtins.has(e.id) || e.extends !== undefined;
+  for (const mode of MODES) {
+    if (e[mode] === undefined && based) continue;
+    if (!isObject(e[mode])) return `${mode} must be an object of colors`;
+    for (const [role, value] of Object.entries(e[mode])) {
+      if (!ROLES.includes(role) && !OPTIONAL_ROLES.includes(role)) return `${mode}.${role} is not a color role`;
+      if (typeof value !== 'string' || !COLOR.test(value)) return `${mode}.${role} is not a color: ${value}`;
+    }
+    const missing = based ? [] : ROLES.filter((r) => !(r in e[mode]));
+    if (missing.length) return `${mode} is missing ${missing.join(', ')}`;
+  }
+  return null;
+}
+
+// The built-in list with the user's themes applied: a built-in id changes that theme in place, a
+// new id is added at the end. A theme that breaks a rule is skipped, and `warn` says why.
+function withUserThemes(themes, entries, warn) {
+  const builtins = new Map(themes.map((t) => [t.id, t]));
+  const out = new Map(builtins);
+  const seen = new Set();
+  entries.forEach((e, i) => {
+    const problem = themeProblem(e, builtins, seen);
+    if (problem) {
+      warn(`[themes] skipped ${typeof e?.id === 'string' ? `"${e.id}"` : `entry ${i + 1}`}: ${problem}`);
+      return;
+    }
+    seen.add(e.id);
+    const base = builtins.get(e.id) ?? builtins.get(e.extends);
+    out.set(e.id, {
+      id: e.id,
+      label: e.label ?? base?.label ?? e.id,
+      dark: { ...base?.dark, ...e.dark },
+      light: { ...base?.light, ...e.light },
+    });
+  });
+  return [...out.values()];
+}
+
+function readUserThemes(file, warn) {
+  let entries;
+  try {
+    entries = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') warn(`[themes] skipped ${file}: ${err.message}`);
+    return [];
+  }
+  if (Array.isArray(entries)) return entries;
+  warn(`[themes] skipped ${file}: it must hold a JSON array of themes`);
+  return [];
+}
+
+function readRegistry(file = THEMES_FILE) {
+  try {
+    return readThemes(file);
+  } catch {
+    return null;
+  }
+}
+
+// What /api/config carries. An unreadable registry gives empty maps: the hub keeps index.html's
+// colors and sends no vars, so each app uses its own theme CSS. `userFile` is the user's
+// <hub-dir>/themes.json, read on each call.
+function themeConfig(registry = readRegistry(), { userFile, warn = console.warn } = {}) {
+  if (!registry) return { themes: [], themeVars: {} };
+  const themes = userFile ? withUserThemes(registry, readUserThemes(userFile, warn), warn) : registry;
+  return {
+    themes: themes.map((t) => ({ id: t.id, label: t.label, swatch: modes(t, swatch) })),
+    themeVars: Object.fromEntries(themes.map((t) => [t.id, modes(t, coreVars)])),
+  };
+}
+
+module.exports = { readThemes, readRegistry, coreVars, swatch, themeConfig, ROLES };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "0.42.0",
+  "version": "1.0.1",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -9,14 +9,15 @@
   "scripts": {
     "start": "node server.js",
     "dev": "node server.js --open",
-    "test": "node --test test/*.test.js",
+    "test": "node --test test/*.test.js packages/claude-hub-sdk/test/*.test.js",
     "update": "bash scripts/update-submodules.sh",
     "update:check": "bash scripts/update-submodules.sh --check",
-    "lint": "npx @biomejs/biome check public/app.js server.js && npm run check:escaping && npm run check:security-lib",
-    "lint:fix": "npx @biomejs/biome check --fix public/app.js server.js",
+    "lint": "npx @biomejs/biome check public/app.js server.js packages/claude-hub-sdk && npm run check:escaping && npm run check:security-lib",
+    "lint:fix": "npx @biomejs/biome check --fix public/app.js server.js packages/claude-hub-sdk",
     "prepare": "husky",
     "check:escaping": "node scripts/check-escaping.mjs",
     "check:security-lib": "bash scripts/sync-security-lib.sh --check",
+    "sdk:sync": "node scripts/sdk-sync.mjs",
     "perf": "node scripts/perf.mjs run",
     "perf:compare": "node scripts/perf.mjs compare",
     "perf:report": "node scripts/perf.mjs report",
@@ -44,10 +45,10 @@
   },
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
-    "claude-code-cost": "^0.26.0",
-    "claude-code-kanban": "^4.31.1",
-    "claude-code-marketplace": "^0.22.0",
-    "claude-code-memory-explorer": "^0.17.0",
+    "claude-code-cost": "1.0.0",
+    "claude-code-kanban": "5.1.0",
+    "claude-code-marketplace": "1.0.0",
+    "claude-code-memory-explorer": "1.0.0",
     "express": "^4.21.0",
     "open": "^10.1.0"
   },
@@ -57,7 +58,9 @@
   "files": [
     "server.js",
     "public/**/*",
-    "lib/**/*"
+    "lib/**/*",
+    "plugin/**/*",
+    "packages/claude-hub-sdk/src/**/*"
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",