agentproc 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentproc",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "AgentProc Protocol SDK + CLI for Node.js — connect any Agent CLI to a messaging platform",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/cli.js

@@ -41,6 +41,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const runner = require('./runner.js');
+const hub = require('./hub.js');
 const { PROTOCOL_VERSION } = runner;
 
 const PKG_VERSION = require('../package.json').version;
@@ -57,7 +58,7 @@ function parseArgs(argv) {
     sessionName: 'default',
     from: '',
     cwd: null,
-    env: {},
+    env: [],  // array of "KEY=VALUE" strings; --env can repeat
     timeout: null,
     stream: true,
     verbose: true,
@@ -83,20 +84,21 @@ function parseArgs(argv) {
       case '--session-name': opts.sessionName = next(); break;
       case '--from': opts.from = next(); break;
       case '--cwd': opts.cwd = next(); break;
-      case '--env': {
-        const kv = next();
-        const eq = kv.indexOf('=');
-        if (eq < 0) throw new Error(`--env expects KEY=VALUE, got: ${kv}`);
-        opts.env[kv.slice(0, eq)] = kv.slice(eq + 1);
+      case '--env':
+        opts.env.push(next());
         break;
-      }
       case '--timeout': opts.timeout = parseInt(next(), 10); break;
-      case '--no-stream': opts.stream = false; break;
+      case '--no-stream': opts.noStream = true; break;
       case '--verbose': opts.verbose = true; break;
       case '--quiet': opts.verbose = false; break;
       case '--raw': opts.raw = true; break;
       case '--stdin': opts.stdin = true; break;
       default:
+        if (a === 'hub' && extras.length === 0) {
+          opts.hub = true;
+          opts.hubArgs = argv.slice(i + 1);
+          return { opts, extras };
+        }
         if (a.startsWith('--')) throw new Error(`unknown option: ${a}`);
         extras.push(a);
     }
@@ -104,6 +106,204 @@ function parseArgs(argv) {
   return { opts, extras };
 }
 
+// ---------------------------------------------------------------------------
+// Hub subcommand dispatcher
+// ---------------------------------------------------------------------------
+
+async function runHubSubcommand(args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    showHubHelp();
+    return 0;
+  }
+
+  // Parse common flags
+  const refresh = rest.includes('--refresh');
+  const positional = rest.filter(a => !a.startsWith('--'));
+
+  if (sub === 'list') {
+    const profiles = await hub.listProfiles({
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    process.stdout.write('Available profiles in the official hub:\n\n');
+    for (const p of profiles) {
+      process.stdout.write(
+        `  ${p.name.padEnd(15)} ${p.tested.padEnd(12)} ${p.description.slice(0, 60)}\n`
+      );
+    }
+    process.stdout.write(`\nRun \`agentproc hub run <name> -p "hi"\` to use one.\n`);
+    return 0;
+  }
+
+  if (sub === 'show') {
+    if (!positional[0]) {
+      process.stderr.write('error: hub show requires a profile name\n');
+      return 2;
+    }
+    const readme = await hub.showReadme(positional[0], {
+      refresh,
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    process.stdout.write(readme);
+    if (!readme.endsWith('\n')) process.stdout.write('\n');
+    return 0;
+  }
+
+  if (sub === 'install') {
+    if (!positional[0]) {
+      process.stderr.write('error: hub install requires a profile name\n');
+      return 2;
+    }
+    const target = process.cwd();
+    await hub.installProfile(positional[0], target, {
+      refresh,
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    return 0;
+  }
+
+  if (sub === 'run') {
+    if (!positional[0]) {
+      process.stderr.write('error: hub run requires a profile name\n');
+      return 2;
+    }
+    const profileName = positional[0];
+    const cacheDir = await hub.fetchProfile(profileName, {
+      refresh,
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    const profilePath = path.join(cacheDir, 'profile.yaml');
+
+    // Re-parse the remaining args as the runner options (--prompt, --cwd, etc.).
+    const { opts: runOpts } = parseArgs(rest);
+    if (!runOpts.prompt && !runOpts.stdin) {
+      process.stderr.write('error: hub run requires --prompt <text> or --stdin\n');
+      return 2;
+    }
+
+    return await runAgent(profilePath, runOpts);
+  }
+
+  process.stderr.write(`error: unknown hub subcommand: ${sub}\n\n`);
+  showHubHelp();
+  return 2;
+}
+
+function showHubHelp() {
+  process.stdout.write(`agentproc hub — manage profiles from the official Hub
+
+Usage:
+  agentproc hub list                       List all profiles in the hub
+  agentproc hub show <name>                Show a profile's README
+  agentproc hub install <name>             Copy a profile to the current directory
+  agentproc hub run <name> [run-options]   Fetch (if needed) and run a profile
+
+Hub run options (same as the regular --profile runner):
+  -p, --prompt <text>          User message (or use --stdin)
+  --cwd <path>                 Override profile.cwd (default: current dir)
+  --env KEY=VALUE              Extra env var (repeatable)
+  --session <id>               Previous session id for multi-turn
+  --timeout <secs>             Override profile.timeout_secs
+  --no-stream                  Disable streaming
+  --verbose / --quiet          Protocol line visibility (default: verbose)
+  --stdin                      Read prompt from stdin
+
+Common options:
+  --refresh                    Force re-fetch from GitHub (ignore cache)
+  -h, --help                   Show this help
+
+Examples:
+  agentproc hub list
+  agentproc hub run echo-agent -p "hello"
+  cd ~/projects/my-app && agentproc hub run claude-code -p "explain this" --env ANTHROPIC_API_KEY=$KEY
+  agentproc hub show codex
+  agentproc hub install agy
+
+Profiles are cached at ~/.agentproc/cache/hub/<name>/ (24h TTL).
+`);
+}
+
+/**
+ * Shared runner logic used by both `agentproc --profile` and `agentproc hub run`.
+ * Kept here for the hub subcommand to reuse; the legacy main() path also calls it.
+ */
+async function runAgent(profilePath, opts) {
+  let profileRaw;
+  try {
+    const yamlText = fs.readFileSync(path.resolve(profilePath), 'utf8');
+    profileRaw = parseYaml(yamlText);
+  } catch (e) {
+    process.stderr.write(`error: failed to read profile ${profilePath}: ${e.message}\n`);
+    return 2;
+  }
+
+  // Read prompt.
+  let prompt = opts.prompt;
+  if (opts.stdin) {
+    prompt = fs.readFileSync(0, 'utf8').replace(/\n$/, '');
+  }
+  if (prompt == null) {
+    process.stderr.write('error: --prompt (or --stdin) is required\n');
+    return 2;
+  }
+
+  // opts.env is an array of "KEY=VALUE" strings (from repeated --env flags)
+  const extraEnv = {};
+  for (const kv of opts.env || []) {
+    const eq = kv.indexOf('=');
+    if (eq < 0) {
+      process.stderr.write(`error: --env expects KEY=VALUE, got: ${kv}\n`);
+      return 2;
+    }
+    extraEnv[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+
+  const streaming = opts.noStream ? false : null;
+
+  if (opts.raw) {
+    const r = await runner.run(profileRaw, {
+      message: prompt,
+      sessionId: opts.session || '',
+      sessionName: opts.sessionName || 'default',
+      fromUser: opts.from || '',
+      streaming,
+      cwd: opts.cwd,
+      extraEnv,
+      timeoutSecs: opts.timeout,
+    });
+    process.stdout.write(r.reply);
+    if (r.reply && !r.reply.endsWith('\n')) process.stdout.write('\n');
+    return r.exitCode === 0 ? 0 : 1;
+  }
+
+  const verbose = opts.verbose || !opts.quiet || (opts.verbose === undefined && opts.quiet === undefined) || opts.verbose;
+
+  const r = await runner.run(profileRaw, {
+    message: prompt,
+    sessionId: opts.session || '',
+    sessionName: opts.sessionName || 'default',
+    fromUser: opts.from || '',
+    streaming,
+    cwd: opts.cwd,
+    extraEnv,
+    timeoutSecs: opts.timeout,
+    onPartial: (t) => { if (verbose) process.stderr.write(`AGENT_PARTIAL:${JSON.stringify(t)}\n`); },
+    onSession: (id) => { if (verbose) process.stderr.write(`AGENT_SESSION:${id}\n`); },
+    onError: (msg) => { if (verbose) process.stderr.write(`AGENT_ERROR:${JSON.stringify(msg)}\n`); },
+    onStderr: (line) => { if (verbose) process.stderr.write(`[agent stderr] ${line}\n`); },
+  });
+
+  if (r.reply) {
+    process.stdout.write(r.reply);
+    if (!r.reply.endsWith('\n')) process.stdout.write('\n');
+  }
+  if (r.sessionId) process.stderr.write(`agentproc:session:${r.sessionId}\n`);
+  if (r.error) process.stderr.write(`agentproc:error:${r.error}\n`);
+  return r.exitCode === 0 ? 0 : 1;
+}
+
 function showHelp() {
   process.stdout.write(`agentproc v${PKG_VERSION} (protocol ${PROTOCOL_VERSION})
 
@@ -392,6 +592,11 @@ async function main() {
   if (opts.help) { showHelp(); process.exit(0); }
   if (opts.version) { showVersion(); process.exit(0); }
 
+  // `agentproc hub <subcommand>` — defer to hub dispatcher.
+  if (opts.hub) {
+    return await runHubSubcommand(opts.hubArgs);
+  }
+
   if (!opts.profile) {
     process.stderr.write('error: --profile is required\n\n');
     showHelp();
@@ -408,89 +613,12 @@ async function main() {
     process.exit(2);
   }
 
-  // Read & parse profile YAML.
-  let profileRaw;
-  try {
-    const yamlText = fs.readFileSync(path.resolve(opts.profile), 'utf8');
-    profileRaw = parseYaml(yamlText);
-  } catch (e) {
-    process.stderr.write(`error: failed to read profile ${opts.profile}: ${e.message}\n`);
-    process.exit(2);
-  }
-
-  // ---- Raw mode: spawn agent, pipe stdout through, exit with agent code ----
-  if (opts.raw) {
-    const { spawn } = require('node:child_process');
-    try {
-      const r = await runner.run(profileRaw, {
-        message: prompt,
-        sessionId: opts.session,
-        sessionName: opts.sessionName,
-        fromUser: opts.from,
-        streaming: opts.stream,
-        cwd: opts.cwd,
-        extraEnv: opts.env,
-        timeoutSecs: opts.timeout,
-        // No callbacks — we replace stdout forwarding below.
-      });
-      // The runner buffers reply; for raw mode we want streaming verbatim,
-      // so we re-implement with raw pipes. Simpler: just print the reply
-      // (which equals the agent's stdout minus protocol lines).
-      // For TRUE raw output (including protocol lines), users should use
-      // the bridge script directly.
-      process.stdout.write(r.reply);
-      if (r.reply && !r.reply.endsWith('\n')) process.stdout.write('\n');
-      process.exit(r.exitCode === 0 ? 0 : 1);
-    } catch (e) {
-      process.stderr.write(`error: ${e.message}\n`);
-      process.exit(1);
-    }
-  }
-
-  // ---- Default mode: classify and pretty-print ----
+  // Read & parse profile YAML, then delegate to the shared runner path.
   try {
-    const r = await runner.run(profileRaw, {
-      message: prompt,
-      sessionId: opts.session,
-      sessionName: opts.sessionName,
-      fromUser: opts.from,
-      streaming: opts.stream,
-      cwd: opts.cwd,
-      extraEnv: opts.env,
-      timeoutSecs: opts.timeout,
-      onPartial: (text) => {
-        if (opts.verbose) process.stderr.write(`AGENT_PARTIAL:${JSON.stringify(text)}\n`);
-      },
-      onSession: (id) => {
-        if (opts.verbose) process.stderr.write(`AGENT_SESSION:${id}\n`);
-      },
-      onError: (msg) => {
-        if (opts.verbose) process.stderr.write(`AGENT_ERROR:${JSON.stringify(msg)}\n`);
-      },
-      onStderr: (line) => {
-        if (opts.verbose) process.stderr.write(`[agent stderr] ${line}\n`);
-      },
-    });
-
-    // Print final reply body to stdout.
-    if (r.reply) {
-      process.stdout.write(r.reply);
-      if (!r.reply.endsWith('\n')) process.stdout.write('\n');
-    }
-
-    // Final session id on stderr (for shell capture).
-    if (r.sessionId) {
-      process.stderr.write(`agentproc:session:${r.sessionId}\n`);
-    }
-
-    if (r.error) {
-      process.stderr.write(`agentproc:error:${r.error}\n`);
-    }
-
-    process.exit(r.exitCode === 0 ? 0 : 1);
+    return await runAgent(opts.profile, opts);
   } catch (e) {
     process.stderr.write(`error: ${e.message}\n`);
-    process.exit(1);
+    return 1;
   }
 }
 

package/src/hub.js

@@ -0,0 +1,310 @@
+'use strict';
+/**
+ * Hub client — fetch and manage profile directories from the official Hub.
+ *
+ * The Hub lives at https://github.com/jeffkit/agentproc/tree/main/hub/
+ * Profiles are cached locally at ~/.agentproc/cache/hub/<name>/ with a
+ * 24-hour TTL. Pass refresh=true to force re-fetch.
+ *
+ * Public API:
+ *   HUB_REPO            — 'jeffkit/agentproc'
+ *   HUB_REF             — 'main'
+ *   HUB_CACHE_TTL_SECS  — 24 hours
+ *   cacheDir(name)      — Path to the local cache directory for a profile
+ *   fetchProfile(name, opts) -> Promise<string>
+ *   listProfiles(opts)  -> Promise<Array<{name, description, cli, tested}>>
+ *   showReadme(name, opts) -> Promise<string>
+ *   installProfile(name, targetDir, opts) -> Promise<string>
+ *
+ * All network access is via global fetch() (Node 18+). Zero dependencies.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const HUB_REPO = 'jeffkit/agentproc';
+const HUB_REF = 'main';
+const HUB_CACHE_TTL_SECS = 24 * 60 * 60;  // 24 hours
+
+const GITHUB_API = (subpath) =>
+  `https://api.github.com/repos/${HUB_REPO}/contents/${subpath}?ref=${HUB_REF}`;
+const GITHUB_TREES = `https://api.github.com/repos/${HUB_REPO}/git/trees/${HUB_REF}?recursive=1`;
+const GITHUB_RAW = (p) =>
+  `https://raw.githubusercontent.com/${HUB_REPO}/${HUB_REF}/${p}`;
+
+// ---------------------------------------------------------------------------
+// Cache helpers
+// ---------------------------------------------------------------------------
+
+function cacheRoot() {
+  // Prefer process.env.HOME (overridable in tests, set by sudo -E etc.),
+  // fall back to os.homedir() (cached at first call on some platforms).
+  const home = process.env.HOME || os.homedir();
+  return path.join(home, '.agentproc', 'cache', 'hub');
+}
+
+function cacheDir(name) {
+  return path.join(cacheRoot(), name);
+}
+
+function cacheAgeSecs(name) {
+  const marker = path.join(cacheDir(name), '.cache-meta.json');
+  if (!fs.existsSync(marker)) return null;
+  try {
+    const meta = JSON.parse(fs.readFileSync(marker, 'utf8'));
+    const ts = meta.fetched_at || 0;
+    return Math.max(0, Date.now() / 1000 - ts);
+  } catch {
+    return null;
+  }
+}
+
+function writeCacheMeta(name) {
+  const dir = cacheDir(name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, '.cache-meta.json'),
+    JSON.stringify({ fetched_at: Date.now() / 1000, ref: HUB_REF }),
+    'utf8'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function httpGetJson(url) {
+  const r = await fetch(url, {
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'User-Agent': 'agentproc-cli',
+    },
+  });
+  if (!r.ok) {
+    const text = await r.text().catch(() => '');
+    throw new Error(`GitHub API ${r.status}: ${text.slice(0, 200)}`);
+  }
+  return r.json();
+}
+
+async function httpGetText(url) {
+  const r = await fetch(url, { headers: { 'User-Agent': 'agentproc-cli' } });
+  if (!r.ok) {
+    throw new Error(`fetch ${r.status}: ${url}`);
+  }
+  return r.text();
+}
+
+/**
+ * Fetch the entire repo tree (1 API call, returns all paths under hub/).
+ * Cached in memory for the lifetime of the process.
+ * @returns {Promise<Array<{path: string, type: 'blob'|'tree'}>>}
+ */
+let _treeCache = null;
+async function getTree() {
+  if (_treeCache) return _treeCache;
+  const data = await httpGetJson(GITHUB_TREES);
+  if (!data || !Array.isArray(data.tree)) {
+    throw new Error('unexpected tree API response');
+  }
+  _treeCache = data.tree
+    .filter((e) => e && typeof e === 'object')
+    .map((e) => ({
+      path: String(e.path || ''),
+      type: String(e.type || ''),  // 'blob' or 'tree'
+    }));
+  return _treeCache;
+}
+
+/**
+ * List top-level entries under a hub subpath (e.g. 'hub/' → all profile dirs).
+ * @param {string} subpath  e.g. 'hub' or 'hub/claude-code'
+ * @returns {Promise<Array<{name: string, type: 'file'|'dir'}>>}
+ */
+async function listRemoteFiles(subpath) {
+  if (!subpath.endsWith('/')) subpath = subpath + '/';
+  const tree = await getTree();
+  const seen = new Set();
+  const out = [];
+  for (const e of tree) {
+    if (!e.path.startsWith(subpath)) continue;
+    const name = e.path.slice(subpath.length).split('/')[0];
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    // Determine type: is there a path equal to subpath+name with type 'tree'?
+    const isDir = tree.some((t) => t.path === subpath + name && t.type === 'tree');
+    out.push({
+      name,
+      type: isDir ? 'dir' : 'file',
+      path: e.path,
+      download_url: '',
+    });
+  }
+  return out;
+}
+
+/**
+ * List actual files inside a hub/<name>/ directory.
+ * @param {string} name
+ * @returns {Promise<Array<{name: string, path: string}>>}
+ */
+async function listRemoteProfileFiles(name) {
+  const prefix = `hub/${name}/`;
+  const tree = await getTree();
+  return tree
+    .filter((e) => e.type === 'blob' && e.path.startsWith(prefix))
+    .map((e) => ({
+      name: e.path.slice(prefix.length).split('/').pop(),
+      path: e.path,
+    }));
+}
+
+async function downloadFile(remotePath, localPath) {
+  const text = await httpGetText(GITHUB_RAW(remotePath));
+  fs.mkdirSync(path.dirname(localPath), { recursive: true });
+  fs.writeFileSync(localPath, text, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a profile directory to local cache. Returns the cache path.
+ *
+ * @param {string} name
+ * @param {{refresh?: boolean, onLog?: function(string): void}} [opts]
+ * @returns {Promise<string>} absolute cache path
+ */
+async function fetchProfile(name, opts = {}) {
+  const { refresh = false, onLog = null } = opts;
+
+  // On refresh, also clear the in-memory tree cache so we see new files
+  // (e.g. profiles added since the process started).
+  if (refresh) _treeCache = null;
+
+  const age = cacheAgeSecs(name);
+  const dir = cacheDir(name);
+  const profileYaml = path.join(dir, 'profile.yaml');
+
+  if (!refresh && age !== null && age < HUB_CACHE_TTL_SECS && fs.existsSync(profileYaml)) {
+    if (onLog) onLog(`using cached profile: ${dir} (age ${Math.floor(age)}s)`);
+    return dir;
+  }
+
+  if (onLog) {
+    if (refresh) {
+      onLog(`refreshing profile '${name}' from ${HUB_REPO}:${HUB_REF}...`);
+    } else {
+      onLog(`fetching profile '${name}' from ${HUB_REPO}:${HUB_REF}...`);
+    }
+  }
+
+  const entries = await listRemoteProfileFiles(name);
+  if (entries.length === 0) {
+    throw new Error(`profile '${name}' not found in hub`);
+  }
+
+  // Clear cache, then re-download every file in the profile directory.
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(dir, { recursive: true });
+
+  for (const entry of entries) {
+    const local = path.join(dir, entry.name);
+    await downloadFile(entry.path, local);
+    if (onLog) onLog(`  - ${entry.name}`);
+  }
+
+  writeCacheMeta(name);
+  return dir;
+}
+
+/**
+ * List profiles in the official hub.
+ *
+ * @param {{refresh?: boolean, onLog?: function(string): void}} [opts]
+ * @returns {Promise<Array<{name: string, description: string, cli: string, tested: string}>>}
+ */
+async function listProfiles(opts = {}) {
+  const { onLog = null } = opts;
+  const entries = await listRemoteFiles('hub');
+  const profiles = [];
+  for (const entry of entries) {
+    if (entry.type !== 'dir') continue;
+    const name = entry.name;
+    try {
+      const yamlText = await httpGetText(GITHUB_RAW(`hub/${name}/profile.yaml`));
+      const { parseYaml } = require('./cli.js');
+      const data = parseYaml(yamlText);
+      profiles.push({
+        name: String(data.name || name),
+        description: String(data.description || ''),
+        cli: String(data.cli || ''),
+        tested: String(data.tested || 'unverified'),
+      });
+    } catch (e) {
+      if (onLog) onLog(`warning: could not read metadata for ${name}: ${e.message}`);
+      profiles.push({
+        name,
+        description: '(failed to read metadata)',
+        cli: '',
+        tested: 'unverified',
+      });
+    }
+  }
+  return profiles;
+}
+
+/**
+ * Return the README.md content for a profile.
+ *
+ * @param {string} name
+ * @param {{refresh?: boolean, onLog?: function(string): void}} [opts]
+ * @returns {Promise<string>}
+ */
+async function showReadme(name, opts = {}) {
+  const dir = await fetchProfile(name, opts);
+  const readme = path.join(dir, 'README.md');
+  if (!fs.existsSync(readme)) {
+    return `(no README.md for profile '${name}')`;
+  }
+  return fs.readFileSync(readme, 'utf8');
+}
+
+/**
+ * Copy a cached profile into targetDir/<name>/.
+ *
+ * @param {string} name
+ * @param {string} targetDir
+ * @param {{refresh?: boolean, onLog?: function(string): void}} [opts]
+ * @returns {Promise<string>} destination path
+ */
+async function installProfile(name, targetDir, opts = {}) {
+  const cached = await fetchProfile(name, opts);
+  const dest = path.join(targetDir, name);
+  if (fs.existsSync(dest)) {
+    throw new Error(`target already exists: ${dest}`);
+  }
+  fs.cpSync(cached, dest, { recursive: true });
+  // Drop our cache meta file from the installed copy.
+  const meta = path.join(dest, '.cache-meta.json');
+  if (fs.existsSync(meta)) fs.unlinkSync(meta);
+  if (opts.onLog) opts.onLog(`installed to: ${dest}`);
+  return dest;
+}
+
+module.exports = {
+  HUB_REPO,
+  HUB_REF,
+  HUB_CACHE_TTL_SECS,
+  cacheRoot,
+  cacheDir,
+  cacheAgeSecs,
+  fetchProfile,
+  listProfiles,
+  showReadme,
+  installProfile,
+};

package/src/hub.test.js

@@ -0,0 +1,327 @@
+'use strict';
+/**
+ * Tests for hub.js — mock-based, no real network access.
+ *
+ * Run with: `node --test src/hub.test.js`
+ *
+ * Strategy: redirect HOME to a tmp dir for cache isolation; intercept
+ * global.fetch with fixtures. Concurrency is disabled because HOME is
+ * process-global state.
+ */
+
+const { test, describe, before, after, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const hub = require('./hub.js');
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const FAKE_TREE = [
+  { path: 'hub', type: 'tree' },
+  { path: 'hub/echo-agent', type: 'tree' },
+  { path: 'hub/echo-agent/profile.yaml', type: 'blob' },
+  { path: 'hub/echo-agent/bridge.py', type: 'blob' },
+  { path: 'hub/echo-agent/bridge.js', type: 'blob' },
+  { path: 'hub/echo-agent/bridge.sh', type: 'blob' },
+  { path: 'hub/echo-agent/README.md', type: 'blob' },
+  { path: 'hub/claude-code', type: 'tree' },
+  { path: 'hub/claude-code/profile.yaml', type: 'blob' },
+  { path: 'hub/claude-code/bridge.py', type: 'blob' },
+  { path: 'hub/claude-code/bridge.js', type: 'blob' },
+  { path: 'hub/claude-code/README.md', type: 'blob' },
+];
+
+const FAKE_FILE_CONTENTS = {
+  'hub/echo-agent/profile.yaml':
+    'name: echo-agent\n' +
+    'description: Minimal hello-world agent\n' +
+    'cli: none\n' +
+    'agentproc:\n' +
+    '  command: python3 ./bridge.py\n' +
+    '  cwd: .\n' +
+    'tested: official\n' +
+    'maintainer: jeffkit\n',
+  'hub/echo-agent/bridge.py': '#!/usr/bin/env python3\nprint("echo")\n',
+  'hub/echo-agent/bridge.js': "'use strict';\nconsole.log('echo');\n",
+  'hub/echo-agent/bridge.sh': '#!/usr/bin/env bash\necho echo\n',
+  'hub/echo-agent/README.md': '# echo-agent\n\nHello world.\n',
+  'hub/claude-code/profile.yaml':
+    'name: claude-code\n' +
+    'description: Claude Code wrapper\n' +
+    'cli: claude\n' +
+    'agentproc:\n' +
+    '  command: python3 ./bridge.py\n' +
+    'tested: official\n' +
+    'maintainer: jeffkit\n',
+  'hub/claude-code/bridge.py': '#!/usr/bin/env python3\nprint("claude")\n',
+  'hub/claude-code/bridge.js': "'use strict';\nconsole.log('claude');\n",
+  'hub/claude-code/README.md': '# claude-code\n\nReal wrapper.\n',
+};
+
+let _origHome = null;
+let _tmpHome = null;
+
+function setupHome() {
+  _origHome = process.env.HOME;
+  _tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-hub-home-'));
+  process.env.HOME = _tmpHome;
+}
+
+function teardownHome() {
+  if (_origHome !== null) process.env.HOME = _origHome;
+  if (_tmpHome && fs.existsSync(_tmpHome)) {
+    fs.rmSync(_tmpHome, { recursive: true, force: true });
+  }
+  _tmpHome = null;
+}
+
+/**
+ * Install a fake global.fetch that serves our fixtures.
+ */
+function installFakeFetch(tree = FAKE_TREE, contents = FAKE_FILE_CONTENTS) {
+  const counter = { json: 0, text: 0 };
+  const orig = global.fetch;
+  global.fetch = async (url, opts) => {
+    const acceptJson = opts && opts.headers && opts.headers.Accept && opts.headers.Accept.includes('json');
+    if (acceptJson && url.includes('git/trees')) {
+      counter.json++;
+      return {
+        ok: true,
+        json: async () => ({ tree }),
+        text: async () => JSON.stringify({ tree }),
+      };
+    }
+    if (acceptJson) {
+      throw new Error(`unexpected JSON URL: ${url}`);
+    }
+    for (const [p, content] of Object.entries(contents)) {
+      if (url.endsWith(p)) {
+        counter.text++;
+        return { ok: true, text: async () => content };
+      }
+    }
+    throw new Error(`unexpected text URL: ${url}`);
+  };
+  counter.restore = () => { global.fetch = orig; };
+  return counter;
+}
+
+
+// ---------------------------------------------------------------------------
+// All tests live inside this suite so we can disable concurrency.
+// (Mutating process.env.HOME is global state; parallel tests would clash.)
+// ---------------------------------------------------------------------------
+
+describe('hub', { concurrency: false }, () => {
+  beforeEach(setupHome);
+  afterEach(teardownHome);
+
+  // ----- cacheAgeSecs -----
+
+  describe('cacheAgeSecs', () => {
+    test('null when not cached', () => {
+      assert.strictEqual(hub.cacheAgeSecs('never'), null);
+    });
+
+    test('small age right after write', () => {
+      fs.mkdirSync(hub.cacheDir('fresh'), { recursive: true });
+      fs.writeFileSync(
+        path.join(hub.cacheDir('fresh'), '.cache-meta.json'),
+        JSON.stringify({ fetched_at: Date.now() / 1000, ref: 'main' })
+      );
+      const age = hub.cacheAgeSecs('fresh');
+      assert.ok(age !== null);
+      assert.ok(age < 5);
+    });
+
+    test('large age for stale cache', () => {
+      fs.mkdirSync(hub.cacheDir('stale'), { recursive: true });
+      fs.writeFileSync(
+        path.join(hub.cacheDir('stale'), '.cache-meta.json'),
+        JSON.stringify({ fetched_at: Date.now() / 1000 - 100000, ref: 'main' })
+      );
+      const age = hub.cacheAgeSecs('stale');
+      assert.ok(age !== null);
+      assert.ok(age >= 99999, `age=${age}`);
+    });
+
+    test('null for invalid meta', () => {
+      fs.mkdirSync(hub.cacheDir('bad'), { recursive: true });
+      fs.writeFileSync(
+        path.join(hub.cacheDir('bad'), '.cache-meta.json'),
+        'not json at all'
+      );
+      assert.strictEqual(hub.cacheAgeSecs('bad'), null);
+    });
+  });
+
+  // ----- fetchProfile -----
+
+  describe('fetchProfile', () => {
+    test('downloads all files', async () => {
+      const counter = installFakeFetch();
+      try {
+        const dir = await hub.fetchProfile('echo-agent');
+        assert.ok(fs.existsSync(dir));
+        const names = fs.readdirSync(dir).sort();
+        assert.ok(names.includes('profile.yaml'));
+        assert.ok(names.includes('bridge.py'));
+        assert.ok(names.includes('bridge.js'));
+        assert.ok(names.includes('README.md'));
+        assert.ok(names.includes('.cache-meta.json'));
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('unknown profile raises', async () => {
+      const counter = installFakeFetch([{ path: 'hub', type: 'tree' }]);
+      try {
+        await assert.rejects(hub.fetchProfile('nope'), /not found in hub/);
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('uses cache on second call (no new fetches)', async () => {
+      const counter = installFakeFetch();
+      try {
+        await hub.fetchProfile('echo-agent');
+        const afterFirst = { json: counter.json, text: counter.text };
+        await hub.fetchProfile('echo-agent');
+        assert.strictEqual(counter.json, afterFirst.json);
+        assert.strictEqual(counter.text, afterFirst.text);
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('refresh forces refetch', async () => {
+      const counter = installFakeFetch();
+      try {
+        await hub.fetchProfile('echo-agent');
+        const first = counter.json;
+        await hub.fetchProfile('echo-agent', { refresh: true });
+        assert.ok(counter.json > first);
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('overwrites tampered cache on refresh', async () => {
+      const counter = installFakeFetch();
+      try {
+        await hub.fetchProfile('echo-agent');
+        const f = path.join(hub.cacheDir('echo-agent'), 'bridge.py');
+        const original = fs.readFileSync(f, 'utf8');
+        fs.writeFileSync(f, '# tampered\n');
+        await hub.fetchProfile('echo-agent', { refresh: true });
+        assert.strictEqual(fs.readFileSync(f, 'utf8'), original);
+      } finally {
+        counter.restore();
+      }
+    });
+  });
+
+  // ----- listProfiles -----
+
+  describe('listProfiles', () => {
+    test('returns all profile dirs with metadata', async () => {
+      const counter = installFakeFetch();
+      try {
+        const profiles = await hub.listProfiles({ refresh: true });
+        const names = profiles.map(p => p.name).sort();
+        assert.deepStrictEqual(names, ['claude-code', 'echo-agent']);
+        const ec = profiles.find(p => p.name === 'echo-agent');
+        assert.strictEqual(ec.tested, 'official');
+        assert.strictEqual(ec.description, 'Minimal hello-world agent');
+        assert.strictEqual(ec.cli, 'none');
+      } finally {
+        counter.restore();
+      }
+    });
+  });
+
+  // ----- showReadme -----
+
+  describe('showReadme', () => {
+    test('returns README content', async () => {
+      const counter = installFakeFetch();
+      try {
+        const text = await hub.showReadme('echo-agent', { refresh: true });
+        assert.ok(text.includes('echo-agent'));
+        assert.ok(text.includes('Hello world'));
+      } finally {
+        counter.restore();
+      }
+    });
+
+    test('missing README returns placeholder', async () => {
+      const tree = [
+        { path: 'hub', type: 'tree' },
+        { path: 'hub/noreadme', type: 'tree' },
+        { path: 'hub/noreadme/profile.yaml', type: 'blob' },
+      ];
+      const contents = {
+        'hub/noreadme/profile.yaml': 'name: noreadme\ndescription: x\ntested: unverified\n',
+      };
+      const counter = installFakeFetch(tree, contents);
+      try {
+        const text = await hub.showReadme('noreadme', { refresh: true });
+        assert.ok(text.includes('no README.md'));
+      } finally {
+        counter.restore();
+      }
+    });
+  });
+
+  // ----- installProfile -----
+
+  describe('installProfile', () => {
+    test('copies to target dir', async () => {
+      const counter = installFakeFetch();
+      const tmpTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-install-'));
+      try {
+        const dest = await hub.installProfile('echo-agent', tmpTarget, { refresh: true });
+        assert.ok(fs.existsSync(dest));
+        assert.ok(fs.existsSync(path.join(dest, 'profile.yaml')));
+        assert.ok(fs.existsSync(path.join(dest, 'bridge.py')));
+        assert.ok(!fs.existsSync(path.join(dest, '.cache-meta.json')));
+      } finally {
+        counter.restore();
+        fs.rmSync(tmpTarget, { recursive: true, force: true });
+      }
+    });
+
+    test('refuses existing target', async () => {
+      const counter = installFakeFetch();
+      const tmpTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-install-'));
+      try {
+        await hub.installProfile('echo-agent', tmpTarget, { refresh: true });
+        await assert.rejects(
+          hub.installProfile('echo-agent', tmpTarget, { refresh: true }),
+          /target already exists/
+        );
+      } finally {
+        counter.restore();
+        fs.rmSync(tmpTarget, { recursive: true, force: true });
+      }
+    });
+  });
+
+  // ----- Constants (no HOME mutation needed) -----
+
+  test('HUB_CACHE_TTL_SECS is 24h', () => {
+    assert.strictEqual(hub.HUB_CACHE_TTL_SECS, 24 * 60 * 60);
+  });
+
+  test('hub repo constants', () => {
+    assert.strictEqual(hub.HUB_REPO, 'jeffkit/agentproc');
+    assert.strictEqual(hub.HUB_REF, 'main');
+  });
+});