claude-code-hub 1.28.0 → 1.30.0

package/README.md

@@ -183,12 +183,15 @@ The shortcuts also work when focus is inside a tool. Kanban keeps <kbd>Ctrl</kbd
 --host <addr>           Bind address (default: 127.0.0.1)
 --allowed-hosts <list>  Extra host names to accept, comma-separated
 --open                  Open the browser on start
+--show-token            Print the URL with its token also when output is not a terminal
 --detached              Keep running when stdin closes (the macOS tray uses it)
 --tray                  Windows, macOS: run the hub from a tray icon
 --autostart             Windows, macOS: same as --tray, and start the tray at logon
 --no-autostart          Windows, macOS: stop starting the tray at logon
 --tray-status           Windows, macOS: show whether autostart is on and the tray and hub are running
 --app-id <id>           Windows, macOS, with --tray or --autostart: the installed app that Open Hub starts
+-v, --version           Print the version
+-h, --help              Print the flags
 ```
 
 If a port is busy, the hub uses a free port and reports it.

package/lib/cli.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const { version: HUB_VERSION } = require('../package.json');
+
+// Every flag the hub reads, and whether it takes a value. `--<app id>-port` is open-ended, because
+// config.json can add apps.
+const FLAGS = {
+  port: true,
+  'hub-dir': true,
+  'pool-size': true,
+  'disable-terminal': false,
+  'no-mods': false,
+  host: true,
+  'allowed-hosts': true,
+  open: false,
+  'show-token': false,
+  detached: false,
+  install: false,
+  uninstall: false,
+  dir: true,
+  tray: false,
+  autostart: false,
+  'no-autostart': false,
+  'tray-status': false,
+  'app-id': true,
+  version: false,
+  help: false,
+};
+const SHORT = { '-v': 'version', '-h': 'help' };
+const APP_PORT_RE = /^[a-z0-9-]+-port$/;
+
+const HELP = `Claude Code Hub ${HUB_VERSION}
+
+Usage:
+  claude-code-hub [options]       Start the hub, or print the URL of the one that runs
+  claude-code-hub ext <command>   Manage extensions (claude-code-hub ext --help)
+
+Options:
+  --port <n>                      Hub port (default 3540)
+  --<app>-port <n>                Port of an app: kanban, marketplace, cost, memory
+  --hub-dir <path>                Hub dir (default ~/.claude-hub)
+  --pool-size <n>                 Config dirs kept running (default 3)
+  --disable-terminal              Turn off the embedded terminal in Kanban
+  --no-mods                       Start without mods
+  --host <addr>                   Bind address (default 127.0.0.1)
+  --allowed-hosts <list>          Extra host names to accept, comma-separated
+  --open                          Open the hub in the browser
+  --show-token                    Print the hub URL with its token also when output is not a terminal
+  --detached                      Keep running when stdin closes
+  --install, --uninstall          Install or remove the hub plugin (--dir <config dir>)
+  --tray, --autostart, --no-autostart, --tray-status, --app-id <id>
+                                  Tray and start at login (Windows and macOS)
+  -v, --version                   Print the version
+  -h, --help                      Print this help`;
+
+// {exit, out} when the command line is answered here: the version, the help, or a usage error.
+// {} when the hub should go on. `ext` keeps its own parser.
+function checkArgs(args) {
+  if (args[0] === 'ext') return {};
+  const bad = (what) => ({ exit: 1, out: `${what}\n\n${HELP}` });
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('-')) return bad(i === 0 ? `Unknown command: ${arg}` : `Unexpected argument: ${arg}`);
+    const [flag, value] = arg.startsWith('--') ? [arg.slice(2).split('=')[0], arg.includes('=')] : [SHORT[arg], false];
+    const takes = FLAGS[flag] ?? (APP_PORT_RE.test(flag ?? '') || undefined);
+    if (takes === undefined) return bad(`Unknown option: ${arg}`);
+    if (flag === 'version') return { exit: 0, out: HUB_VERSION };
+    if (flag === 'help') return { exit: 0, out: HELP };
+    if (takes && !value) i++;
+  }
+  return {};
+}
+
+// The hub URL as printed. Off a terminal (an agent's shell, a pipe, the tray's hub.log) the output is
+// kept or read by others, so the token is hidden unless --show-token asks for it.
+function printedUrl(line, url, { show, tokenFile }) {
+  if (show) return `${line} ${url}`;
+  const hidden = url.replace(/([?&]token=)[^&]*/, '$1<hidden>');
+  return `${line} ${hidden}\n  The token is hidden. Open the hub with --open, print it with --show-token, or read ${tokenFile}`;
+}
+
+module.exports = { HUB_VERSION, FLAGS, HELP, checkArgs, printedUrl };

package/lib/ext.js

@@ -9,7 +9,7 @@ const { APPS, HUB_ROOT, ID_RE, selectApps, appRoot, readApp } = require('./apps'
 const { isContained } = require('./contain');
 const { readConfig, writeConfigFile } = require('./hub-config');
 const { claudeEnv, hasClaude, installPlugin, reinstallPlugin, uninstallPlugin, report, run } = require('./install');
-const { BUNDLED, bundledRoot, entryRoot, modJsHash, readMod } = require('./mods');
+const { BUNDLED, bundledRoot, entryRoot, readMod } = require('./mods');
 const { pluginChecker } = require('./plugin-status');
 const { isNewer } = require('./update-check');
 
@@ -31,12 +31,15 @@ const USAGE = `Usage: claude-code-hub ext <command>
 
   A mod (mod.json) adds CSS and JS to the hub page and the apps, and can bring color themes.
   The hub ships some mods (xmas): ext install <id> finds them before the registry.
-  A mod with JS runs only when you type y, at install and when ext update changes its code.
   Open the hub at /?nomods to load it with no mod. "modsEnabled": false in config.json
   or --no-mods turns every mod off.
 
   --hub-dir <path>       The hub dir (default CLAUDE_HUB_DIR, else ~/.claude-hub)
-  --yes                  Let a mod run code without asking
+  An extension from GitHub or a folder runs code with your rights: its server, its plugin's hooks
+  and its JS in the hub's pages. ext install and ext update say what runs and ask y/N first.
+  An extension the hub ships (xmas, voice) does not ask.
+
+  --yes                  Install or update without asking
   --dir <path>           The config dir for plugin and dock steps (default CLAUDE_CONFIG_DIR, else ~/.claude)`;
 
 const RESTART = '  Restart the hub to load the change.';
@@ -248,6 +251,10 @@ const KINDS = {
     file: 'hub-app.json',
     read: readApp,
     step: (ctx, _id, ext, step, root) => !ext?.plugin || pluginStep(ctx, ext.plugin, step, root),
+    code: (ext) => [
+      ['a server the hub starts', 'a server'],
+      ...(ext.plugin ? [[`Claude Code plugin ${ext.plugin.id}, in your sessions`, `plugin ${ext.plugin.id}`]] : []),
+    ],
     stepName: 'Plugin install',
     removeName: 'Plugin removal',
     unread: 'The plugin is not removed, because the manifest does not name it.',
@@ -261,6 +268,7 @@ const KINDS = {
     file: 'addon.json',
     read: readAddon,
     step: dockStep,
+    code: (ext) => (ext.manifest.run ? [['a server Kanban starts', 'a server']] : []),
     stepName: 'Putting it on the dock',
     removeName: 'Taking it off the dock',
     unread: 'It is taken off the dock by its id.',
@@ -273,8 +281,12 @@ const KINDS = {
     list: 'mods',
     file: 'mod.json',
     read: readMod,
-    step: modStep,
-    stepName: 'Checking the mod',
+    step: () => true,
+    // A mod's JS runs in the page's own origin: in Kanban's it can read the terminal token and type into sessions.
+    code: (ext) => {
+      const js = jsTargets(ext.manifest);
+      return js.length ? [[`JS in ${js.join(', ')}`, `JS in ${js.join(', ')}`]] : [];
+    },
     removeName: 'Removing the mod',
     unread: 'It is removed by its id.',
     installed: RESTART,
@@ -305,13 +317,17 @@ function askTerminal(question) {
   }
 }
 
-// A mod's JS runs in the page's own origin, with the same trust as a patch: in Kanban's origin it can
-// read the terminal token and type into sessions. So it runs only when the user types yes.
-function allowJs(ctx, id, js, refused) {
+// Code from a clone or a folder runs only when the user types yes, at install and at each update that
+// moves it. An extension with no code, such as a CSS-only mod, does not ask.
+function consent(ctx, { head, code, verb, update, refused }) {
+  if (!code.length) return true;
+  console.log(`\n  ${head}`);
+  if (update) console.log(`  It runs with your rights: ${code.map(([, s]) => s).join(', ')}`);
+  else console.log(`  It runs with your rights:\n${code.map(([l]) => `    ${l}`).join('\n')}`);
   if (ctx.yes) return true;
-  const answer = (ctx.ask ?? askTerminal)(`  Let ${id} run code in ${js.join(', ')}? [y/N] `);
+  const answer = (ctx.ask ?? askTerminal)(`  ${verb} it? [y/N] `);
   if (answer === null) {
-    console.log(`\n  There is no terminal to ask on. Pass --yes to let ${id} run code.`);
+    console.log(`\n  There is no terminal to ask on. Pass --yes to ${verb.toLowerCase()} it.`);
     return false;
   }
   if (/^y(es)?$/i.test(answer)) return true;
@@ -319,33 +335,8 @@ function allowJs(ctx, id, js, refused) {
   return false;
 }
 
-// Asks only at install. Update asks itself, and only when the code changes.
-function modStep(ctx, id, ext, step) {
-  if (step !== 'install' || !ext) return true;
-  const { targets } = ext.manifest;
-  console.log(`\n  Mod ${id} changes: ${Object.keys(targets).join(', ')}`);
-  const js = jsTargets(ext.manifest);
-  if (!js.length) return true;
-  console.log(`  It runs code in ${js.join(', ')}, with the same access as the app's own code.`);
-  return allowJs(ctx, id, js, `${id} is not installed.`);
-}
-
-function jsHashOf(root, id) {
-  try {
-    return modJsHash(root, readMod(root, id).manifest);
-  } catch {
-    return null;
-  }
-}
-
-function updateAllowed(ctx, id, kind, root, before) {
-  if (kind !== KINDS.mod) return true;
-  const { manifest } = readMod(root, id);
-  const js = jsTargets(manifest);
-  if (!js.length || modJsHash(root, manifest) === before) return true;
-  console.log(`\n  The new version of ${id} changes the code it runs in ${js.join(', ')}.`);
-  return allowJs(ctx, id, js, `${id} keeps the code it had.`);
-}
+const askInstall = (ctx, id, kind, ext, from) =>
+  consent(ctx, { head: `${id} from ${from}`, code: kind.code(ext), verb: 'Install', refused: `${id} is not installed.` });
 
 // An id the hub runs gets its plugin installed. A folder is added to the hub, with its plugin, unless the
 // hub already runs it from there; then only the plugin is installed. Any other name is looked up in the registry.
@@ -482,6 +473,10 @@ function installGithub(ctx, target, file, config, name) {
       return true;
     }
     checkRequires(ctx, ext.manifest, config);
+    if (!askInstall(ctx, id, kind, ext, `${src.source} at ${short(sha)}`)) {
+      removeDir(dir);
+      return false;
+    }
   } catch (e) {
     removeDir(dir);
     throw e;
@@ -545,6 +540,7 @@ function installFolder(ctx, target, file, config) {
     return true;
   }
   const linked = root.replaceAll('\\', '/');
+  if (!askInstall(ctx, id, kind, ext, linked)) return false;
   if (!addExtension(ctx, root, file, config, { path: linked, source: 'local' }, kind)) return false;
   console.log(`\n  Linked ${id} to ${linked}.\n${kind.installed}`);
   return true;
@@ -578,17 +574,22 @@ function update(ctx, id) {
   const [entry, kind] = managedEntry(config, id, 'update');
   const root = rootOf(ctx, entry);
   let sha;
+  let ext;
   if (isGithub(entry)) {
     const clone = cloneOf(ctx, entry);
-    const before = kind === KINDS.mod ? jsHashOf(root, id) : null;
     const was = git(['rev-parse', 'HEAD'], clone);
     git(['fetch', '--quiet', 'origin'], clone);
     sha = checkout(clone, entry.ref);
     const back = () => was !== sha && checkout(clone, was);
-    let allowed;
+    let allowed = true;
     try {
-      checkRequires(ctx, kind.read(root, id).manifest, config);
-      allowed = updateAllowed(ctx, id, kind, root, before);
+      ext = kind.read(root, id);
+      checkRequires(ctx, ext.manifest, config);
+      if (sha !== was) {
+        const n = git(['rev-list', '--count', `${was}..${sha}`], clone);
+        const head = `${id} ${short(was)} -> ${short(sha)} (${n} commit${n === '1' ? '' : 's'})`;
+        allowed = consent(ctx, { head, code: kind.code(ext), verb: 'Update', update: true, refused: `${id} keeps the code it had.` });
+      }
     } catch (e) {
       back();
       throw e;
@@ -598,9 +599,10 @@ function update(ctx, id) {
       return false;
     }
   } else {
-    checkRequires(ctx, kind.read(root, id).manifest, config);
+    ext = kind.read(root, id);
+    checkRequires(ctx, ext.manifest, config);
   }
-  if (!kind.step(ctx, id, kind.read(root, id), 'reinstall', root, config)) return false;
+  if (!kind.step(ctx, id, ext, 'reinstall', root, config)) return false;
   if (sha && sha !== entry.sha) writeConfigFile(file, withList(config, kind, (list) => list.map((e) => (e === entry ? { ...e, sha } : e))));
   const at = sha ? ` to ${short(sha)}` : '';
   console.log(`\n  Updated ${id}${at}. ${kind.updated}`);

package/lib/mods.js

@@ -76,14 +76,6 @@ function readSurface(root) {
   }
 }
 
-// Changes with any JS file of the mod, and with the page each one runs in. `ext update` asks again when it does.
-function modJsHash(root, manifest) {
-  const hash = crypto.createHash('sha1');
-  for (const [target, parts] of Object.entries(manifest.targets))
-    for (const f of parts.js ?? []) hash.update(`${target}\0${f}\0`).update(fs.readFileSync(path.join(root, f))).update('\0');
-  return hash.digest('hex');
-}
-
 // The mods of `config.mods`, read once at hub start. `version` changes with any file of the mod,
 // so the browser fetches the new files after a hub restart and caches them until then.
 // `surfaces` maps "hub" and each enabled app id to its surface version, or null when it has none.
@@ -153,4 +145,4 @@ function hubModScript(assets) {
   ].join('\n');
 }
 
-module.exports = { BUNDLED, readMod, readSurface, modJsHash, entryRoot, bundledRoot, resolveMods, modAssets, appModEnv, hubModScript };
+module.exports = { BUNDLED, readMod, readSurface, entryRoot, bundledRoot, resolveMods, modAssets, appModEnv, hubModScript };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -47,7 +47,7 @@
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
     "claude-code-cost": "1.6.1",
-    "claude-code-kanban": "7.26.0",
+    "claude-code-kanban": "7.27.0",
     "claude-code-marketplace": "1.7.2",
     "claude-code-memory-explorer": "1.3.5",
     "express": "^4.21.0",

package/server.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+const { HUB_VERSION, checkArgs, printedUrl } = require('./lib/cli');
+
+// Before the other requires: -v and -h answer at once, and a bad flag never reaches the running-hub check,
+// which prints the hub URL with its token.
+const cli = checkArgs(process.argv.slice(2));
+if (cli.exit !== undefined) {
+  (cli.exit ? console.error : console.log)(cli.out);
+  process.exit(cli.exit);
+}
+
 const { spawn } = require('child_process');
 const crypto = require('crypto');
 const express = require('express');
@@ -33,7 +43,6 @@ const {
   MAX_POOL_SIZE,
   settingValues,
 } = require('./lib/settings');
-const { version: HUB_VERSION } = require('./package.json');
 
 function getArg(name) {
   const idx = process.argv.findIndex((a) => a.startsWith(`--${name}`));
@@ -1464,7 +1473,7 @@ if (!TRAY_FLAG) {
       listenWithFallback(app, HUB_PORT, onReady, '');
       return;
     }
-    console.log(`Claude Code Hub already runs for ${HUB_DIR} at ${accessUrl(running.port)}`);
+    printUrl(`Claude Code Hub already runs for ${HUB_DIR} at`, running.port);
     if (process.argv.includes('--open')) {
       import('open').then((m) => m.default(accessUrl(running.port))).finally(() => process.exit(0));
     } else {
@@ -1477,8 +1486,13 @@ function accessUrl(port) {
   return `http://localhost:${port}/?token=${HUB_TOKEN}`;
 }
 
+function printUrl(line, port) {
+  const show = process.argv.includes('--show-token') || require('tty').isatty(1);
+  console.log(printedUrl(line, accessUrl(port), { show, tokenFile: HUB_TOKEN_FILE }));
+}
+
 function printBanner(port) {
-  console.log(`Claude Code Hub running at ${accessUrl(port)}`);
+  printUrl('Claude Code Hub running at', port);
   const warning = net.exposureWarning();
   if (warning) console.log(warning);
   console.log('Type "q" or "exit" to stop the server');