create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,346 @@
+'use strict';
+
+/**
+ * WP-7 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-11, the D-11 decision + cadence rows,
+ * §6.2 `GET /api/agent-skills/inventory`, §6.5, the WP-7 row AC-7a..AC-7d): THE RETURN PATH — the box
+ * reports the skills it already holds, and the hub classifies each one against its own copy and the
+ * base (the tree that box last received).
+ *
+ * Two halves in one module, because they are two views of one question ("what does the box have that
+ * we do not?"):
+ *
+ *   BOX  `readBoxInventory({ homeDir, env, dataDir, peerInstanceId })` — enumerate the box's own
+ *        Claude/Codex skill roots (the SAME enumeration build.js ships: its listers, its walk, its
+ *        item hash), say which copies CTM owns, and hand back the base for the AUTHENTICATED caller.
+ *   HUB  `classifyBoxSkills({ hubItems, baseItems, boxSkills })` — pure, five rules, first match wins.
+ *
+ * BASE, not the hub's push record (the lead's superseding adjustment): the hub's push bookkeeping is
+ * in-process (`lib/machine-registry.js`'s `_agentBundlePush`) and dies with a restart, so the box —
+ * which still holds the tree it was given — carries the base back with its inventory. Classification
+ * therefore survives a hub restart.
+ *
+ * D-11 is "inventory + classification, NEVER auto-copy": nothing here writes to either side, and
+ * nothing is ever copied. A box-local skill SHADOWS the hub's added-dir copy of the same name on
+ * Claude 2.1.310 (observed: exactly one `zz-collide-*` loaded, the box-local one) — hence
+ * `shadows_hub` is a first-class state rather than an assumption that both copies load.
+ *
+ * AC-7d: a copy CTM itself put there is never classified — `delegate` (the managed-skill installer's
+ * own skill) and a pristine WP-6 Codex install both read `managed` and drop out of the matrix. An
+ * EDITED agent-bundle copy is the box's own work now, so it reads `managed: null` and IS classified.
+ */
+
+const os = require('os');
+const path = require('path');
+const fsp = require('fs/promises');
+
+const { computeTreeHash, itemHashOfDir, listClaudeSkillItems, listCodexSkillItems } = require('./build');
+const store = require('./store');
+// WP-6's directory hash: the hash a WP-6 marker`sha256` is written from. Deliberately NOT
+// `itemHashOfDir` — a bundle copy is "pristine" when ITS OWN hash still matches what the installer
+// recorded, and those two hashes are different functions of the same bytes (D-14).
+const { dirHash } = require('./codex-install');
+const installer = require('../coding-cli-skill-installer');
+
+const { MANAGED_SKILLS } = installer;
+const { readMarker } = installer._internals;
+
+/**
+ * `source` strings on disk. Both live in modules this one does not own, and both are ON-DISK
+ * contract values (a marker is read back by a different process and a different release), so they
+ * are restated here as data rather than reached for across module boundaries.
+ */
+const INSTALLER_SOURCE = 'ctm-coding-cli-skill-installer'; // lib/coding-cli-skill-installer.js SOURCE
+const AGENT_BUNDLE_SOURCE = 'agent-bundle'; // lib/agent-bundle/codex-install.js SOURCE
+
+/**
+ * The three manifest entry roots (store.js PATH_PREFIXES, build.js entryPrefix) read BACKWARDS:
+ * an entry path is `<prefix><item folder>/<rel file path>`, and the folder segment is what names
+ * the item. Order is irrelevant — the three are disjoint.
+ */
+const ITEM_PREFIXES = Object.freeze([
+  Object.freeze({ prefix: 'claude/.claude/skills/', agent: 'claude', kind: 'skill' }),
+  Object.freeze({ prefix: 'plugins/', agent: 'claude', kind: 'plugin' }),
+  Object.freeze({ prefix: 'codex/', agent: 'codex', kind: 'skill' }),
+]);
+
+/** The five classification states (§6.5), in rule order. Exported so a test can pin "nothing else". */
+const BOX_SKILL_STATES = Object.freeze([
+  'new_on_box', 'same', 'shadows_hub', 'changed_on_box', 'conflict',
+]);
+
+function _compareStrings(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+async function _statOrNull(target) {
+  try {
+    return await fsp.stat(target);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+    throw err; // RETHROW: a real stat fault is the caller's to REPORT
+  }
+}
+
+async function _realOrPlain(target) {
+  try {
+    return await fsp.realpath(target);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return target;
+    throw err; // RETHROW: a real resolution fault is the caller's to REPORT
+  }
+}
+
+async function _readJsonOrNull(target) {
+  let text;
+  try {
+    text = await fsp.readFile(target, 'utf8');
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+    throw err; // RETHROW: a real read fault must not read as "no manifest"
+  }
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    // expected: a torn/garbled manifest copy is missing information about the base, never a reason to
+    // fail the inventory — the base is a hint for classification, not a fact the box must prove.
+    return null;
+  }
+}
+
+/** The box's Claude config dir, by the same rule build.js uses for the hub's own. */
+function claudeConfigDir(homeDir, env) {
+  const configured = env && typeof env.CLAUDE_CONFIG_DIR === 'string' ? env.CLAUDE_CONFIG_DIR.trim() : '';
+  return configured || path.join(homeDir, '.claude');
+}
+
+/** The box's Codex home, by the same rule build.js uses (`$CODEX_HOME`, else `<home>/.codex`). */
+function codexHomeDir(homeDir, env) {
+  const configured = env && typeof env.CODEX_HOME === 'string' ? env.CODEX_HOME.trim() : '';
+  return configured || path.join(homeDir, '.codex');
+}
+
+/**
+ * The skill roots this inventory enumerates, in build.js's order, realpath'd when they exist (a
+ * Dropbox-symlinked `.claude` is the observed real shape). The Codex `.agents` root and a
+ * `$CODEX_HOME` that resolves to the same directory are one root, never two rows.
+ */
+async function _rootsFor(homeDir, env) {
+  const claudeRoot = await _realOrPlain(path.join(claudeConfigDir(homeDir, env), 'skills'));
+  const agentsRoot = path.join(homeDir, '.agents', 'skills');
+  const codexRoots = [agentsRoot];
+  const configuredRoot = path.join(codexHomeDir(homeDir, env), 'skills');
+  if (configuredRoot !== agentsRoot) codexRoots.push(configuredRoot);
+  const roots = [{ agent: 'claude', root: claudeRoot }];
+  for (const root of codexRoots) roots.push({ agent: 'codex', root: await _realOrPlain(root) });
+  return roots;
+}
+
+/**
+ * AC-7d + §6.2: who owns this copy on the box.
+ *
+ *   'ctm-managed'   a `MANAGED_SKILLS` name (the managed-skill installer's `delegate`), or a marker
+ *                   the installer itself wrote — CTM's own release, never the hub's bundle.
+ *   'agent-bundle'  a WP-6 Codex install of THIS hub's tree whose bytes still hash to the marker's
+ *                   `sha256` — it IS the hub's bundle, not the box's own work.
+ *   null            anything else: a user-authored skill, another installer's copy, or an
+ *                   agent-bundle copy the box has EDITED since (that is box work now, and D-11
+ *                   exists precisely to surface it).
+ */
+async function _managedFor(item) {
+  if (Object.hasOwn(MANAGED_SKILLS, item.name)) return 'ctm-managed';
+  const marker = await readMarker(item.rootDir, item.name);
+  if (!marker) return null;
+  if (marker.source === INSTALLER_SOURCE) return 'ctm-managed';
+  if (marker.source !== AGENT_BUNDLE_SOURCE) return null;
+  const current = await dirHash(item.rootDir);
+  return typeof marker.sha256 === 'string' && marker.sha256 === current ? 'agent-bundle' : null;
+}
+
+/**
+ * §6.2 base: the item list of the tree the box currently holds for the CALLING hub, derived from the
+ * manifest copy the store keeps beside the materialized tree (`trees/<hex>.manifest.json`).
+ *
+ * The derivation is the inverse of build.js's `entryPrefix`: strip the item prefix, take the first
+ * segment as the item folder, keep the rest as the item-relative path — then hash exactly the entry
+ * shape build.js hashes, so `baseItems[i].itemHash` IS `buildAgentBundle(...).items[i].itemHash` for
+ * the same tree (`tests/agent-bundle-inventory.test.js` proves it against a fixture bundle).
+ *
+ * @returns {Array<{agent: string, kind: string, name: string, itemHash: string}>}
+ */
+function baseItemsFromManifest(manifest) {
+  const entries = manifest && Array.isArray(manifest.entries) ? manifest.entries : [];
+  const groups = new Map();
+  for (const entry of entries) {
+    if (!entry || typeof entry.path !== 'string') continue;
+    const matched = ITEM_PREFIXES.find((candidate) => entry.path.startsWith(candidate.prefix));
+    if (!matched) continue;
+    const rest = entry.path.slice(matched.prefix.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0) continue; // no folder segment: not an item
+    const name = rest.slice(0, slash);
+    const rel = rest.slice(slash + 1);
+    if (!rel) continue;
+    const key = `${matched.agent}\0${matched.kind}\0${name}`;
+    if (!groups.has(key)) {
+      groups.set(key, { agent: matched.agent, kind: matched.kind, name, files: [] });
+    }
+    groups.get(key).files.push({ path: rel, mode: entry.mode, sha256: entry.sha256, size: entry.size });
+  }
+  return [...groups.values()]
+    .map((group) => ({
+      agent: group.agent,
+      kind: group.kind,
+      name: group.name,
+      itemHash: computeTreeHash(group.files),
+    }))
+    .sort((a, b) => _compareStrings(a.agent, b.agent)
+      || _compareStrings(a.kind, b.kind)
+      || _compareStrings(a.name, b.name));
+}
+
+/** The base block for one authenticated hub: `{treeHash, items}`, or the empty base when it has none. */
+async function _baseFor(dataDir, peerInstanceId) {
+  const empty = { treeHash: null, items: [] };
+  if (!dataDir || !peerInstanceId) return empty;
+  const treeHash = await store.currentHubTree(dataDir, peerInstanceId);
+  if (!treeHash) return empty;
+  const manifest = await _readJsonOrNull(
+    path.join(store.storeRoot(dataDir), 'trees', `${treeHash.replace(/^sha256:/, '')}.manifest.json`),
+  );
+  if (!manifest) return { treeHash, items: [] };
+  return { treeHash, items: baseItemsFromManifest(manifest) };
+}
+
+/**
+ * §6.2 `GET /api/agent-skills/inventory`: the box's own skill truth, plus the base for the
+ * AUTHENTICATED caller (never a body/query field — lib/api/agent-bundles.js reads
+ * `req.ctmAuth.peerInstanceId`).
+ *
+ * Read-only, and never a write to the box user's `~/.claude` (D-1): the box's roots are ENUMERATED
+ * here exactly as build.js enumerates the hub's (`synced/` and `.system` excluded by the shared
+ * listers), and each item is hashed with build.js's own `itemHashOfDir`.
+ *
+ * @param {object} opts
+ * @param {string} [opts.homeDir=os.homedir()] the box user's home
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env]
+ * @param {string|null} [opts.dataDir] the box's CTM data dir (null ⇒ no base to report)
+ * @param {string} [opts.peerInstanceId] the AUTHENTICATED hub
+ * @param {() => number} [opts.now=Date.now] injected clock, so no test needs a sleep
+ * @returns {Promise<{platform: string, checkedAt: number, roots: object[], skills: object[],
+ *                    base: {treeHash: string|null, items: object[]}}>}
+ */
+async function readBoxInventory({
+  homeDir = os.homedir(),
+  env = process.env,
+  dataDir = null,
+  peerInstanceId = '',
+  now = Date.now,
+} = {}) {
+  const resolvedHome = String(homeDir == null ? '' : homeDir).replace(/\/+$/, '') || '/';
+  const configDir = claudeConfigDir(resolvedHome, env);
+  const [roots, claudeItems, codexItems, base] = await Promise.all([
+    _rootsFor(resolvedHome, env),
+    listClaudeSkillItems(configDir),
+    listCodexSkillItems(resolvedHome, env),
+    _baseFor(dataDir, String(peerInstanceId == null ? '' : peerInstanceId).trim()),
+  ]);
+
+  const skills = [];
+  for (const item of [...claudeItems, ...codexItems]) {
+    const stat = await _statOrNull(item.rootDir);
+    if (!stat || !stat.isDirectory()) continue; // vanished between enumeration and hashing
+    const itemHash = await itemHashOfDir(item.rootDir);
+    if (itemHash === null) continue; // vanished mid-walk: not an item this time
+    skills.push({
+      agent: item.agent,
+      name: item.name,
+      itemHash,
+      managed: await _managedFor(item),
+      mtimeMs: stat.mtimeMs,
+    });
+  }
+  skills.sort((a, b) => _compareStrings(a.agent, b.agent) || _compareStrings(a.name, b.name));
+
+  return {
+    platform: process.platform,
+    checkedAt: Number(typeof now === 'function' ? now() : Date.now()) || 0,
+    roots,
+    skills,
+    base,
+  };
+}
+
+function _skillKey(agent, name) {
+  return `${agent}\0${name}`;
+}
+
+function _skillItems(items) {
+  const map = new Map();
+  for (const item of Array.isArray(items) ? items : []) {
+    // §6.5: Claude PLUGINS are never box inventory — the box reports skills only, so a plugin item
+    // can never be the hub-side counterpart of a box row. Filtered here rather than at each call.
+    if (!item || item.kind !== 'skill' || typeof item.name !== 'string') continue;
+    map.set(_skillKey(item.agent, item.name), item.itemHash);
+  }
+  return map;
+}
+
+/**
+ * §6.5/AC-7a: classify every UNMANAGED box skill against the hub's copy and the base. Pure — no I/O,
+ * no clock, no state — so the five rules are provable from a fixture matrix alone.
+ *
+ * Rules, IN ORDER (first match wins; `(agent, name)` is the matching key):
+ *   1. no hub item                 -> `new_on_box`      the hub has nothing here; Import would add it
+ *   2. box == hub                  -> `same`            the box copy is redundant; Retire is offered
+ *   3. box == base && hub != base  -> `shadows_hub`     the box copy HIDES the hub's newer one
+ *   4. hub == base && box != base  -> `changed_on_box`  the box edited its copy; Import fast-forwards
+ *   5. otherwise                   -> `conflict`        both moved: the user picks
+ *
+ * AC-7d: a managed copy (`managed: 'ctm-managed' | 'agent-bundle'`) is never classified — CTM put it
+ * there, so it is not a proposal the user is being asked to review.
+ *
+ * @returns {Array<{agent: string, name: string, state: string, boxHash: string, hubHash: string|null,
+ *                  baseHash: string|null}>} sorted by (agent, name)
+ */
+function classifyBoxSkills({ hubItems = [], baseItems = [], boxSkills = [] } = {}) {
+  const hub = _skillItems(hubItems);
+  const base = _skillItems(baseItems);
+  const rows = [];
+  for (const box of Array.isArray(boxSkills) ? boxSkills : []) {
+    if (!box || typeof box.name !== 'string') continue;
+    if (box.managed !== null && box.managed !== undefined) continue; // AC-7d
+    const key = _skillKey(box.agent, box.name);
+    const boxHash = box.itemHash;
+    const hubHash = hub.has(key) ? hub.get(key) : null;
+    const baseHash = base.has(key) ? base.get(key) : null;
+    let state;
+    if (hubHash === null) state = 'new_on_box';
+    else if (boxHash === hubHash) state = 'same';
+    else if (boxHash === baseHash && hubHash !== baseHash) state = 'shadows_hub';
+    else if (hubHash === baseHash && boxHash !== baseHash) state = 'changed_on_box';
+    else state = 'conflict';
+    rows.push({ agent: box.agent, name: box.name, state, boxHash, hubHash, baseHash });
+  }
+  rows.sort((a, b) => _compareStrings(a.agent, b.agent) || _compareStrings(a.name, b.name));
+  return rows;
+}
+
+module.exports = {
+  BOX_SKILL_STATES,
+  ITEM_PREFIXES,
+  // The box half. `itemHashOfDir` is build.js's own (re-exported, never re-implemented) so a box
+  // item hash and a hub item hash of identical bytes are the same number by construction.
+  itemHashOfDir,
+  // WP-8: the export/retire legs resolve the SAME roots and apply the SAME ownership rules as this
+  // inventory, so "the same skill" and "is it exportable" cannot drift between the rows the hub
+  // renders and the folder the box moves aside.
+  claudeConfigDir,
+  managedStateOf: _managedFor,
+  baseItemsFromManifest,
+  readBoxInventory,
+  // The hub half.
+  classifyBoxSkills,
+};