claude-code-hub 1.11.0 → 1.12.0

package/README.md

@@ -77,13 +77,13 @@ npm start        # http://localhost:3540
 
 ## Agent observability (one-time setup)
 
-For the full Kanban view (agent log, live subagent tracking, waiting-for-user indicators, and context window use), install the hooks:
+For the full Kanban view (agent log, live subagent tracking, waiting-for-user indicators, and context window use), install the plugins:
 
 ```bash
-npx claude-code-kanban --install
+claude-code-hub --install
 ```
 
-Without the hooks you still get the task board and sessions, but no live agent activity. The hooks and status line are installed per Claude config dir, so run the command again for each dir you use. See the [Kanban docs](https://nikiforovall.blog/claude-code-kanban/) for details.
+This installs Kanban's plugin and the hub's own plugin. Without Kanban's plugin you still get the task board and sessions, but no live agent activity. The plugins are installed per Claude config dir, so run the command again with `--dir <config dir>` for each dir you use. After a hub update, run the command again to update the plugins. See the [Kanban docs](https://nikiforovall.blog/claude-code-kanban/) for details.
 
 ## Hub token
 

package/lib/apps.js

@@ -18,6 +18,7 @@ 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;
+const isObject = (x) => typeof x === 'object' && x !== null && !Array.isArray(x);
 
 // `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.
@@ -37,7 +38,17 @@ function selectApps(entries = [], base = process.cwd()) {
   const apps = [...order]
     .map(byId)
     .filter((a) => a && !off.has(a.id))
-    .map((a) => ({ ...a, port: entryOf(a.id)?.port, path: pathOf(a.id) }));
+    .map((a) => {
+      const e = entryOf(a.id);
+      return {
+        ...a,
+        port: e?.port,
+        path: pathOf(a.id),
+        hidden: e?.hidden === true,
+        deferredStart: e?.deferredStart === true,
+        linked: e?.source === 'local',
+      };
+    });
   return { apps, unknown };
 }
 
@@ -66,24 +77,109 @@ function manifestError(m, id, root) {
   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) ?? keysError(m.keys) ?? pluginError(m.plugin, root);
+  return (
+    providesError(m.provides) ??
+    publishesError(m.publishes) ??
+    keysError(m.keys) ??
+    pluginError(m.plugin, root) ??
+    requiresError(m.requires) ??
+    listingError(m.listing, root)
+  );
 }
 
-const PLUGIN_ID_RE = /^[\w.-]+@[\w.-]+$/;
+const PLUGIN_NAME_RE = /^[\w.-]+$/;
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
 
 function pluginError(plugin, root) {
   if (plugin === undefined) return null;
-  if (typeof plugin?.id !== 'string' || !PLUGIN_ID_RE.test(plugin.id)) return 'plugin.id is not <name>@<marketplace>';
-  if (typeof plugin.path !== 'string') return 'plugin.path is missing';
-  const dir = path.resolve(root, plugin.path);
-  if (dir === path.resolve(root) || !isContained(dir, root)) return 'plugin.path is outside the app directory';
-  if (typeof plugin.install !== 'string' || !plugin.install) return 'plugin.install is missing';
+  if (!isObject(plugin)) return 'plugin is not an object';
+  if (typeof plugin.marketplace !== 'string') return 'plugin.marketplace is not a path';
+  if (!isContained(path.resolve(root, plugin.marketplace), root)) return 'plugin.marketplace is outside the app directory';
+  if (typeof plugin.name !== 'string' || !PLUGIN_NAME_RE.test(plugin.name)) return 'plugin.name is not a plugin name';
+  if (plugin.install !== undefined && (typeof plugin.install !== 'string' || !plugin.install))
+    return 'plugin.install is not a command';
   return null;
 }
 
+function requiresError(requires) {
+  if (requires === undefined) return null;
+  if (!isObject(requires)) return 'requires is not an object';
+  for (const key of ['hub', 'node']) {
+    const v = requires[key];
+    if (v !== undefined && (typeof v !== 'string' || !VERSION_RE.test(v))) return `requires.${key} is not a version x.y.z`;
+  }
+  const { apps } = requires;
+  if (apps !== undefined && (!Array.isArray(apps) || !apps.every((id) => typeof id === 'string' && ID_RE.test(id))))
+    return 'requires.apps is not a list of app ids';
+  return null;
+}
+
+const TAG_RE = /^[a-z0-9-]+$/;
+const IMAGE_RE = /\.(png|jpe?g|webp)$/i;
+const SPDX_RE = /^[A-Za-z0-9.+-]+$/;
+const isHttps = (u) => typeof u === 'string' && /^https:\/\/[^\s/]+/.test(u);
+const textError = (key, v, max) =>
+  v === undefined || (typeof v === 'string' && v.length > 0 && v.length <= max && !/[<>]/.test(v))
+    ? null
+    : `listing.${key} is not plain text of ${max} characters or fewer`;
+
+function listingError(listing, root) {
+  if (listing === undefined) return null;
+  if (!isObject(listing)) return 'listing is not an object';
+  const err = textError('tagline', listing.tagline, 80) ?? textError('description', listing.description, 500) ?? textError('author', listing.author, 60);
+  if (err) return err;
+  const { tags, screenshots, homepage, license } = listing;
+  if (tags !== undefined && (!Array.isArray(tags) || tags.length > 5 || !tags.every((t) => typeof t === 'string' && TAG_RE.test(t))))
+    return 'listing.tags is not a list of up to 5 lowercase tags';
+  if (screenshots !== undefined) {
+    if (!Array.isArray(screenshots) || screenshots.length > 4) return 'listing.screenshots is not a list of up to 4';
+    for (const s of screenshots) {
+      if (!isObject(s) || typeof s.alt !== 'string' || !s.alt) return 'listing.screenshots entry has no alt';
+      const text = textError('screenshots.title', s.title, 40) ?? textError('screenshots.caption', s.caption, 200);
+      if (text) return text;
+      if ((s.path === undefined) === (s.url === undefined)) return 'listing.screenshots entry needs one of path or url';
+      const file = s.path ?? s.url;
+      if (typeof file !== 'string' || !IMAGE_RE.test(file)) return 'listing.screenshots entry is not a PNG, JPEG or WebP file';
+      if (s.url !== undefined && !isHttps(s.url)) return 'listing.screenshots url is not https';
+      if (s.path !== undefined && !isContained(path.resolve(root, s.path), root)) return 'listing.screenshots path is outside the app directory';
+    }
+  }
+  if (homepage !== undefined && !isHttps(homepage)) return 'listing.homepage is not an https URL';
+  if (license !== undefined && (typeof license !== 'string' || !SPDX_RE.test(license))) return 'listing.license is not an SPDX id';
+  return null;
+}
+
+// The plugin id, its folder, the hub command a user runs to install it, and `custom`, the manifest's own install
+// command that the hub command runs. The id and folder come from marketplace.json, so this throws when it does not
+// list the plugin as a folder inside the app directory.
+function resolvePlugin(plugin, root, appId) {
+  const dir = path.resolve(root, plugin.marketplace);
+  const file = path.join(dir, '.claude-plugin', 'marketplace.json');
+  let market;
+  try {
+    market = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`${file}: ${e.code === 'ENOENT' ? 'not found' : e.message}`);
+  }
+  if (typeof market?.name !== 'string' || !PLUGIN_NAME_RE.test(market.name)) throw new Error(`${file}: name is not a marketplace name`);
+  const listed = Array.isArray(market.plugins) ? market.plugins.find((p) => p?.name === plugin.name) : undefined;
+  if (!listed) throw new Error(`${file} does not list plugin "${plugin.name}"`);
+  if (typeof listed.source !== 'string') throw new Error(`${file}: the source of "${plugin.name}" is not a folder`);
+  const pluginDir = path.resolve(dir, listed.source);
+  if (!isContained(pluginDir, root)) throw new Error(`${file}: the source of "${plugin.name}" is outside the app directory`);
+  return {
+    id: `${plugin.name}@${market.name}`,
+    dir: pluginDir,
+    bundled: bundledVersion(pluginDir),
+    marketplace: { dir, name: market.name },
+    install: `claude-code-hub ext install ${appId}`,
+    custom: plugin.install ?? null,
+  };
+}
+
 function keysError(keys) {
   if (keys === undefined) return null;
-  if (typeof keys !== 'object' || keys === null || Array.isArray(keys)) return 'keys is not an object';
+  if (!isObject(keys)) return 'keys is not an object';
   if (keys.keeps === undefined) return null;
   if (!Array.isArray(keys.keeps)) return 'keys.keeps is not an array';
   for (const c of keys.keeps) {
@@ -111,7 +207,7 @@ 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';
+  if (!isObject(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];
@@ -120,11 +216,17 @@ function providesError(provides) {
   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 manifest at root and its resolved plugin. With no id, the manifest's own id is checked. Throws with the file and the reason.
+function readApp(root, id) {
+  const file = path.join(root, 'hub-app.json');
+  try {
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const err = manifestError(manifest, id ?? manifest?.id, root);
+    if (err) throw new Error(err);
+    return { manifest, plugin: manifest.plugin && resolvePlugin(manifest.plugin, root, manifest.id) };
+  } catch (e) {
+    throw new Error(`${file}: ${e.code === 'ENOENT' ? 'not found' : e.message}`);
+  }
 }
 
 // The entry's path, else the submodule when it is checked out, else the installed package.
@@ -152,29 +254,27 @@ function userPort(app, flagPort, log) {
 function loadApp(app, { flagPort, hubRoot = HUB_ROOT, resolve = require.resolve, log = console.log } = {}) {
   const root = appRoot(app, hubRoot, resolve);
   let manifest;
+  let plugin;
   try {
-    manifest = readManifest(root, app.id);
+    ({ manifest, plugin } = readApp(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`);
+    log(`${e.message}. ${app.id} is skipped`);
     return null;
   }
   let version = null;
   try {
     version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version ?? null;
   } catch {}
-  const { plugin } = manifest;
   return {
     id: app.id,
     version,
-    plugin: plugin && {
-      id: plugin.id,
-      bundled: bundledVersion(path.join(root, plugin.path)),
-      install: plugin.install,
-    },
+    plugin: plugin && { id: plugin.id, bundled: plugin.bundled, install: plugin.install },
     entry: path.join(root, manifest.run.entry),
     port: userPort(app, flagPort, log) ?? manifest.run.defaultPort ?? 0,
     name: manifest.name ?? app.id,
+    hidden: app.hidden === true,
+    deferredStart: app.deferredStart === true,
+    linked: app.linked === true,
     icon: manifest.icon,
     loading: manifest.loading ?? {},
     actions: manifest.actions ?? {},
@@ -184,4 +284,4 @@ function loadApp(app, { flagPort, hubRoot = HUB_ROOT, resolve = require.resolve,
   };
 }
 
-module.exports = { APPS, selectApps, loadApp, manifestError, conflicts };
+module.exports = { APPS, HUB_ROOT, ID_RE, selectApps, appRoot, loadApp, manifestError, readApp, resolvePlugin, conflicts };