create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/agent-bundle/build.js

@@ -0,0 +1,657 @@
+'use strict';
+
+/**
+ * WP-1 — hub-side agent bundle builder (design §6.1, rules D-2/D-3/D-9/D-10).
+ *
+ * Pure except filesystem reads: no network, no persistence, no server wiring.
+ * Later work packages (push, box store, spawn injection) consume this module.
+ *
+ * The bundle is content addressed: `treeHash` is sha256 over the canonical JSON
+ * of the sorted entry list, so identical content yields an identical hash on any
+ * hub, regardless of mtime or directory order (D-2).
+ */
+
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const fsp = require('fs/promises');
+
+/** = box readRawBody cap (api-prompts.js) — larger files cannot be uploaded. */
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+/** Measured hub total is ≈ 9.7 MB; 13× headroom. */
+const MAX_BUNDLE_BYTES = 128 * 1024 * 1024;
+const MAX_ENTRIES = 20000;
+
+/** A file is "text" for the D-10 home-path lint when no NUL byte appears here. */
+const TEXT_PROBE_BYTES = 8192;
+
+/** Claude user skills are never shipped: the account syncs them itself. */
+const SKIPPED_SKILL_DIRS = new Set(['synced']);
+
+/**
+ * Module-scope hash cache, keyed `${realpath}\0${size}\0${mtimeMs}` → sha256 hex.
+ * No disk cache (D-2 keeps identity cheap without a second source of truth).
+ */
+const sha256Cache = new Map();
+
+function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function comparePaths(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Canonical tree hash: sort by path (byte order), keep exactly
+ * {path, mode, sha256, size} in that key order, JSON.stringify, sha256.
+ *
+ * @param {Array<{path: string, mode: number, sha256: string, size: number}>} entries
+ * @returns {string} `sha256:<64 hex>`
+ */
+function computeTreeHash(entries) {
+  const normalized = (Array.isArray(entries) ? entries : [])
+    .map((entry) => ({
+      path: entry.path,
+      mode: entry.mode,
+      sha256: entry.sha256,
+      size: entry.size,
+    }))
+    .sort((a, b) => comparePaths(a.path, b.path));
+  return `sha256:${sha256Hex(JSON.stringify(normalized))}`;
+}
+
+function isInside(root, candidate) {
+  if (candidate === root) return true;
+  return candidate.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+}
+
+function isTextBuffer(buffer) {
+  const probe = buffer.length > TEXT_PROBE_BYTES ? buffer.subarray(0, TEXT_PROBE_BYTES) : buffer;
+  return probe.indexOf(0) === -1;
+}
+
+function stripQuotes(value) {
+  const text = String(value == null ? '' : value).trim();
+  if (text.length >= 2) {
+    const first = text[0];
+    const last = text[text.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}
+
+/**
+ * Narrow YAML reader for `metadata.platforms` only (D-9).
+ *
+ * Deliberately not lib/skill-autocomplete.js's parser: that one flattens nested
+ * keys, so `metadata:` / `  platforms:` would collapse into a bogus top-level
+ * key. Recognizes:
+ *   metadata:
+ *     platforms: [darwin, linux]
+ *   metadata:
+ *     platforms:
+ *       - darwin
+ *
+ * @param {string} text SKILL.md / plugin.json frontmatter source
+ * @returns {string[]|null} platform list, or null when absent
+ */
+function parseFrontmatterPlatforms(text) {
+  const lines = String(text == null ? '' : text).split(/\r?\n/);
+  if (lines.length < 2 || lines[0].trim() !== '---') return null;
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) return null;
+  const frontmatter = lines.slice(1, end);
+
+  let metaIndex = -1;
+  for (let i = 0; i < frontmatter.length; i += 1) {
+    if (/^metadata\s*:\s*$/.test(frontmatter[i])) {
+      metaIndex = i;
+      break;
+    }
+  }
+  if (metaIndex === -1) return null;
+
+  for (let i = metaIndex + 1; i < frontmatter.length; i += 1) {
+    const line = frontmatter[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^\s*/)[0].length;
+    if (indent === 0) return null; // left the metadata block
+    const match = line.match(/^\s+platforms\s*:\s*(.*)$/);
+    if (!match) continue;
+    const inline = match[1].trim();
+    if (inline) {
+      if (inline.startsWith('[') && inline.endsWith(']')) {
+        return inline
+          .slice(1, -1)
+          .split(',')
+          .map((item) => stripQuotes(item))
+          .filter((item) => item.length > 0);
+      }
+      const scalar = stripQuotes(inline);
+      return scalar ? [scalar] : null;
+    }
+    const list = [];
+    for (let j = i + 1; j < frontmatter.length; j += 1) {
+      const item = frontmatter[j];
+      if (!item.trim()) continue;
+      const itemIndent = item.match(/^\s*/)[0].length;
+      const itemMatch = item.match(/^\s*-\s*(.+?)\s*$/);
+      // YAML permits a block sequence either deeper than, or level with, its key.
+      if (!itemMatch || itemIndent < indent) break;
+      list.push(stripQuotes(itemMatch[1]));
+    }
+    return list.length ? list : null;
+  }
+  return null;
+}
+
+/** Platforms declared by a plugin's `.claude-plugin/plugin.json` (`metadata.platforms`). */
+function parsePluginJsonPlatforms(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text));
+  } catch (err) {
+    /* expected: a malformed third-party plugin.json only means "no platform filter" */
+    return null;
+  }
+  const metadata = parsed && typeof parsed === 'object' ? parsed.metadata : null;
+  const platforms = metadata && typeof metadata === 'object' ? metadata.platforms : null;
+  if (!Array.isArray(platforms)) return null;
+  const list = platforms.map((item) => stripQuotes(item)).filter((item) => item.length > 0);
+  return list.length ? list : null;
+}
+
+async function statOrNull(target) {
+  try {
+    return await fsp.stat(target);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+    throw err;
+  }
+}
+
+async function readTextOrNull(target) {
+  try {
+    return await fsp.readFile(target, 'utf8');
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR' || err.code === 'EISDIR')) return null;
+    throw err;
+  }
+}
+
+async function readJsonObjectOrNull(target) {
+  const text = await readTextOrNull(target);
+  if (text == null) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch (err) {
+    /* expected: an unreadable/garbled hub config means "no plugins", not a build failure */
+    return null;
+  }
+}
+
+/**
+ * Claude user skills: every directory directly under realpath(<config>/skills)
+ * that contains SKILL.md, minus `synced`. Entries may be symlinks to dirs — they
+ * are followed. Top-level non-directories are ignored.
+ */
+async function listClaudeSkillItems(configDir) {
+  const skillsDir = path.join(configDir, 'skills');
+  let dirents;
+  try {
+    dirents = await fsp.readdir(skillsDir, { withFileTypes: true });
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return [];
+    throw err;
+  }
+  const items = [];
+  for (const dirent of dirents.slice().sort((a, b) => comparePaths(a.name, b.name))) {
+    const name = dirent.name;
+    if (name.startsWith('.')) continue;
+    if (SKIPPED_SKILL_DIRS.has(name)) continue;
+    const dir = path.join(skillsDir, name);
+    const stat = await statOrNull(dir);
+    if (!stat || !stat.isDirectory()) continue; // stray files (e.g. foo.skill) are ignored
+    const skillMd = await statOrNull(path.join(dir, 'SKILL.md'));
+    if (!skillMd || !skillMd.isFile()) continue;
+    items.push({ agent: 'claude', kind: 'skill', name, dirName: name, rootDir: dir });
+  }
+  return items;
+}
+
+/**
+ * Claude plugins: enabled === true in settings.json `enabledPlugins`, minus the
+ * per-machine exclude list, using the first installed_plugins.json record's
+ * installPath. Missing config files mean "no plugins" (not an error).
+ */
+async function listPluginItems(configDir, excludePlugins) {
+  const installed = await readJsonObjectOrNull(path.join(configDir, 'plugins', 'installed_plugins.json'));
+  const settings = await readJsonObjectOrNull(path.join(configDir, 'settings.json'));
+  if (!installed || !settings) return [];
+  const enabled = settings.enabledPlugins;
+  if (!enabled || typeof enabled !== 'object' || Array.isArray(enabled)) return [];
+  const records = installed.plugins;
+  const recordMap = records && typeof records === 'object' && !Array.isArray(records) ? records : {};
+  const excluded = new Set(Array.isArray(excludePlugins) ? excludePlugins.map(String) : []);
+  const items = [];
+  const dirNames = new Set();
+  for (const id of Object.keys(enabled).sort(comparePaths)) {
+    if (enabled[id] !== true) continue;
+    if (excluded.has(id)) continue;
+    const list = recordMap[id];
+    const first = Array.isArray(list) ? list[0] : null;
+    const installPath = first && typeof first === 'object' && typeof first.installPath === 'string'
+      ? first.installPath
+      : null;
+    const dirName = id.split('@')[0];
+    // Two enabled plugins differing only after '@' would share plugins/<dirName>/; the first
+    // (sorted id) ships, the other is held back rather than producing colliding entry paths.
+    const collides = dirNames.has(dirName);
+    dirNames.add(dirName);
+    items.push({
+      agent: 'claude',
+      kind: 'plugin',
+      name: id,
+      dirName,
+      rootDir: installPath,
+      collides,
+    });
+  }
+  return items;
+}
+
+async function listCodexRoot(rootDir, out, seen) {
+  let dirents;
+  try {
+    dirents = await fsp.readdir(rootDir, { withFileTypes: true });
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return;
+    throw err;
+  }
+  for (const dirent of dirents.slice().sort((a, b) => comparePaths(a.name, b.name))) {
+    const name = dirent.name;
+    if (name.startsWith('.') || name === '.system') continue;
+    if (seen.has(name)) continue; // first root wins (`.agents` before `$CODEX_HOME`)
+    const dir = path.join(rootDir, name);
+    const stat = await statOrNull(dir);
+    if (!stat || !stat.isDirectory()) continue;
+    const skillMd = await statOrNull(path.join(dir, 'SKILL.md'));
+    if (!skillMd || !skillMd.isFile()) continue;
+    seen.add(name);
+    out.push({ agent: 'codex', kind: 'skill', name, dirName: name, rootDir: dir });
+  }
+}
+
+/**
+ * Codex skills: directories under `<homeDir>/.agents/skills` and
+ * `(env.CODEX_HOME || <homeDir>/.codex)/skills`, minus `.system`. On a name
+ * collision the first root (`.agents`) wins.
+ */
+async function listCodexSkillItems(homeDir, env) {
+  const roots = [path.join(homeDir, '.agents', 'skills')];
+  const codexHome = typeof env.CODEX_HOME === 'string' && env.CODEX_HOME.trim()
+    ? env.CODEX_HOME.trim()
+    : path.join(homeDir, '.codex');
+  const codexSkills = path.join(codexHome, 'skills');
+  if (codexSkills !== roots[0]) roots.push(codexSkills);
+  const items = [];
+  const seen = new Set();
+  for (const root of roots) {
+    await listCodexRoot(root, items, seen);
+  }
+  items.sort((a, b) => comparePaths(a.name, b.name));
+  return items;
+}
+
+/**
+ * Recursive walk of one item, sorted by relative POSIX path.
+ * Skips dot-names, sockets/FIFOs/devices, and symlinks whose realpath leaves the
+ * item's realpath root (in-root symlinks are followed and stored as files).
+ *
+ * @returns {Promise<{files?: Array<object>, error?: {reason: string, file: string}}>}
+ */
+async function walkItem(realRoot) {
+  const files = [];
+  const stack = [{ abs: realRoot, rel: '' }];
+  // Real paths of directories already queued: an in-root symlink to an ancestor (a/loop -> ..)
+  // passes the containment check, so without this the walk would never end.
+  const visitedDirs = new Set([realRoot]);
+  while (stack.length) {
+    const current = stack.pop();
+    let dirents;
+    try {
+      dirents = await fsp.readdir(current.abs, { withFileTypes: true });
+    } catch (err) {
+      if (err && err.code === 'ENOENT') continue; // vanished mid-walk
+      return { error: { reason: 'unreadable', file: current.rel } };
+    }
+    const dirs = [];
+    for (const dirent of dirents.slice().sort((a, b) => comparePaths(a.name, b.name))) {
+      const name = dirent.name;
+      if (name.startsWith('.')) continue;
+      const abs = path.join(current.abs, name);
+      const rel = current.rel ? `${current.rel}/${name}` : name;
+      let realAbs = abs;
+      if (dirent.isSymbolicLink()) {
+        try {
+          realAbs = await fsp.realpath(abs);
+        } catch (err) {
+          if (err && err.code === 'ENOENT') continue; // dangling symlink
+          return { error: { reason: 'unreadable', file: rel } };
+        }
+        if (!isInside(realRoot, realAbs)) continue; // escapes the item folder
+      }
+      let stat;
+      try {
+        stat = await fsp.stat(abs);
+      } catch (err) {
+        if (err && err.code === 'ENOENT') continue;
+        return { error: { reason: 'unreadable', file: rel } };
+      }
+      if (stat.isDirectory()) {
+        if (visitedDirs.has(realAbs)) continue;
+        visitedDirs.add(realAbs);
+        dirs.push({ abs, rel });
+        continue;
+      }
+      if (!stat.isFile()) continue; // sockets, FIFOs, devices
+      files.push({
+        rel,
+        abs,
+        realAbs,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+        mode: (stat.mode & 0o111) !== 0 ? 0o555 : 0o444,
+      });
+    }
+    for (let i = dirs.length - 1; i >= 0; i -= 1) stack.push(dirs[i]);
+  }
+  files.sort((a, b) => comparePaths(a.rel, b.rel));
+  return { files };
+}
+
+/**
+ * D-10: first text file (sorted order) whose lines contain the hub home prefix.
+ * @returns {{file: string, line: number}|null}
+ */
+function findHomePathHit(files, textByRel, needle) {
+  for (const file of files) {
+    const text = textByRel.get(file.rel);
+    if (text == null) continue;
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      if (lines[i].includes(needle)) return { file: file.rel, line: i + 1 };
+    }
+  }
+  return null;
+}
+
+function heldBackEntry(item, reason, extra) {
+  return Object.assign(
+    { agent: item.agent, kind: item.kind, name: item.name, reason },
+    extra || {},
+  );
+}
+
+async function platformsForItem(item, realRoot) {
+  if (item.kind === 'plugin') {
+    const text = await readTextOrNull(path.join(realRoot, '.claude-plugin', 'plugin.json'));
+    return text == null ? null : parsePluginJsonPlatforms(text);
+  }
+  const text = await readTextOrNull(path.join(realRoot, 'SKILL.md'));
+  return text == null ? null : parseFrontmatterPlatforms(text);
+}
+
+function entryPrefix(item) {
+  if (item.kind === 'plugin') return `plugins/${item.dirName}/`;
+  if (item.agent === 'codex') return `codex/${item.name}/`;
+  return `claude/.claude/skills/${item.name}/`;
+}
+
+/**
+ * Build the content-addressed bundle description of the hub's agent skills.
+ *
+ * @param {object} opts
+ * @param {'darwin'|'linux'|'win32'} opts.targetPlatform box platform (from its sync manifest probe)
+ * @param {string[]} [opts.excludePlugins]              plugin ids excluded for this machine
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {string} [opts.homeDir]
+ * @returns {Promise<object>} BundleBuild (see design §6.1)
+ */
+async function buildAgentBundle({
+  targetPlatform,
+  excludePlugins = [],
+  env = process.env,
+  homeDir = os.homedir(),
+}) {
+  const resolvedHome = String(homeDir).replace(/\/+$/, '') || '/';
+  const configDir = typeof env.CLAUDE_CONFIG_DIR === 'string' && env.CLAUDE_CONFIG_DIR.trim()
+    ? env.CLAUDE_CONFIG_DIR.trim()
+    : path.join(resolvedHome, '.claude');
+  const needle = `${resolvedHome}/`;
+
+  const items = [
+    ...(await listClaudeSkillItems(configDir)),
+    ...(await listPluginItems(configDir, excludePlugins)),
+    ...(await listCodexSkillItems(resolvedHome, env)),
+  ];
+
+  const entries = [];
+  const acceptedItems = [];
+  const heldBack = [];
+  const warnings = [];
+  const blobsByHash = new Map();
+  let totalBytes = 0;
+  let overLimit = false;
+
+  for (const item of items) {
+    if (overLimit) {
+      heldBack.push(heldBackEntry(item, 'too_large'));
+      continue;
+    }
+    if (item.collides) {
+      heldBack.push(heldBackEntry(item, 'name_collision'));
+      continue;
+    }
+    if (!item.rootDir) {
+      heldBack.push(heldBackEntry(item, 'unreadable'));
+      continue;
+    }
+    let realRoot;
+    try {
+      realRoot = await fsp.realpath(item.rootDir);
+    } catch (err) {
+      if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+        heldBack.push(heldBackEntry(item, 'unreadable'));
+        continue;
+      }
+      throw err;
+    }
+    const rootStat = await statOrNull(realRoot);
+    if (!rootStat || !rootStat.isDirectory()) {
+      heldBack.push(heldBackEntry(item, 'unreadable'));
+      continue;
+    }
+
+    // D-9 platform filter — skipped entirely when the author declared another platform.
+    const platforms = await platformsForItem(item, realRoot);
+    if (Array.isArray(platforms) && platforms.length > 0 && !platforms.includes(targetPlatform)) {
+      heldBack.push(heldBackEntry(item, 'platform', { file: platformFile(item) }));
+      continue;
+    }
+
+    const walked = await walkItem(realRoot);
+    if (walked.error) {
+      heldBack.push(heldBackEntry(item, walked.error.reason, { file: walked.error.file }));
+      continue;
+    }
+    const files = walked.files;
+
+    const oversized = files.find((file) => file.size > MAX_FILE_BYTES);
+    if (oversized) {
+      heldBack.push(heldBackEntry(item, 'too_large', { file: oversized.rel }));
+      continue;
+    }
+
+    const itemBytes = files.reduce((sum, file) => sum + file.size, 0);
+    if (totalBytes + itemBytes > MAX_BUNDLE_BYTES || entries.length + files.length > MAX_ENTRIES) {
+      overLimit = true;
+      heldBack.push(heldBackEntry(item, 'too_large'));
+      continue;
+    }
+
+    const hashed = [];
+    let unreadable = null;
+    const textByRel = new Map();
+    for (const file of files) {
+      let buffer;
+      try {
+        buffer = await fsp.readFile(file.abs);
+      } catch (err) {
+        unreadable = { reason: 'unreadable', file: file.rel };
+        break;
+      }
+      const hash = sha256Cache.get(`${file.realAbs}\0${file.size}\0${file.mtimeMs}`) || sha256Hex(buffer);
+      sha256Cache.set(`${file.realAbs}\0${file.size}\0${file.mtimeMs}`, hash);
+      if (isTextBuffer(buffer)) textByRel.set(file.rel, buffer.toString('utf8'));
+      hashed.push({ rel: file.rel, abs: file.abs, mode: file.mode, size: file.size, sha256: hash });
+    }
+    if (unreadable) {
+      heldBack.push(heldBackEntry(item, unreadable.reason, { file: unreadable.file }));
+      continue;
+    }
+
+    const prefix = entryPrefix(item);
+    const hit = findHomePathHit(hashed, textByRel, needle);
+    if (hit) {
+      if (item.kind === 'plugin') {
+        // D-10: we do not own third-party plugin text — warn, still ship it.
+        warnings.push({
+          kind: 'plugin',
+          name: item.name,
+          reason: 'hub_home_path',
+          file: hit.file,
+          line: hit.line,
+        });
+      } else {
+        heldBack.push(heldBackEntry(item, 'hub_home_path', { file: hit.file, line: hit.line }));
+        continue;
+      }
+    }
+
+    const itemEntries = hashed.map((file) => ({
+      path: `${prefix}${file.rel}`,
+      mode: file.mode,
+      sha256: file.sha256,
+      size: file.size,
+    }));
+    entries.push(...itemEntries);
+    for (const file of hashed) {
+      if (!blobsByHash.has(file.sha256)) blobsByHash.set(file.sha256, file.abs);
+    }
+    totalBytes += itemBytes;
+    acceptedItems.push({
+      agent: item.agent,
+      kind: item.kind,
+      name: item.name,
+      itemHash: computeTreeHash(hashed.map((file) => ({
+        path: file.rel,
+        mode: file.mode,
+        sha256: file.sha256,
+        size: file.size,
+      }))),
+    });
+  }
+
+  entries.sort((a, b) => comparePaths(a.path, b.path));
+
+  return {
+    schema: 1,
+    treeHash: computeTreeHash(entries),
+    entries,
+    items: acceptedItems,
+    heldBack,
+    warnings,
+    blobsByHash,
+  };
+}
+
+function platformFile(item) {
+  return item.kind === 'plugin' ? '.claude-plugin/plugin.json' : 'SKILL.md';
+}
+
+/**
+ * WP-7 (docs/remote-agent-skills-bundles-2026-10-25.html §6.2/§6.5): the build-IDENTICAL
+ * `items[].itemHash` of ONE item folder, for the box's own skill roots.
+ *
+ * This is the same walk (`walkItem`'s dot-name / symlink / mode rules) and the same canonical
+ * entry list `buildAgentBundle` folds into `items[].itemHash` — deliberately NOT
+ * lib/agent-bundle/codex-install.js's `dirHash`, which is a different hash of a different entry
+ * shape (WP-6's marker `sha256`, never comparable with an item hash). The box and the hub
+ * therefore agree on an item hash for identical bytes, which is what the classification rules
+ * compare (`tests/agent-bundle-inventory.test.js`).
+ *
+ * @param {string} rootDir the item folder (an item root, symlinks inside it are followed in-root)
+ * @returns {Promise<string|null>} `sha256:<64 hex>`, or null when the folder has vanished
+ *          (ENOENT/ENOTDIR mid-walk) — an item that is not there is not an item, and a hash for it
+ *          would be a lie. A genuine read fault is RETHROWN for the caller to REPORT.
+ */
+async function itemHashOfDir(rootDir) {
+  let realRoot;
+  try {
+    realRoot = await fsp.realpath(String(rootDir == null ? '' : rootDir));
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+    throw err;
+  }
+  const walked = await walkItem(realRoot);
+  if (walked.error) return null;
+  const hashed = [];
+  for (const file of walked.files) {
+    let buffer;
+    try {
+      buffer = await fsp.readFile(file.abs);
+    } catch (err) {
+      if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null; // vanished mid-walk
+      throw err; // RETHROW: a real read fault is the caller's to REPORT
+    }
+    const key = `${file.realAbs}\0${file.size}\0${file.mtimeMs}`;
+    const hash = sha256Cache.get(key) || sha256Hex(buffer);
+    sha256Cache.set(key, hash);
+    hashed.push({ path: file.rel, mode: file.mode, sha256: hash, size: file.size });
+  }
+  return computeTreeHash(hashed);
+}
+
+module.exports = {
+  buildAgentBundle,
+  computeTreeHash,
+  // WP-7: the box inventory hashes one item folder with the SAME walk and the SAME canonical entry
+  // list the builder uses — this export is the one hasher, so the two can never drift.
+  itemHashOfDir,
+  // WP-7: the box enumerates ITS skill roots with the SAME listers the hub enumerates its own
+  // (`synced/` skipped for Claude, `.system` skipped for Codex, `.agents` before `$CODEX_HOME`), so
+  // "the same skill" means the same folder on both sides.
+  listClaudeSkillItems,
+  listCodexSkillItems,
+  // WP-8: the export leg (`lib/agent-bundle/skill-transfer.js`) ships ONE item's bytes, and it walks
+  // that folder with THIS walk — the same dot-name/symlink/`isFile` rules the hub's own builder uses —
+  // so an exported item and a hub-built item of identical bytes carry the same entry list by
+  // construction, never by a second implementation of the same rules.
+  walkItem,
+  MAX_FILE_BYTES,
+  MAX_BUNDLE_BYTES,
+  MAX_ENTRIES,
+};