Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
23.5 KB
Raw Blame
#!/usr/bin/env bun
/**
 * scripts/generate-plugin-tree.ts — generator for the committed `plugin/`
 * tree that the Codex and Claude Code plugin lanes ship as their skill set.
 *
 * Repo-only release/CI tooling — deliberately NOT wired into src/cli.ts
 * (same posture as generate-template-repo.ts). Consumers:
 *   - the committed `plugin/` tree at the repo root (regenerate after any
 *     curation or bundled-skill change: `bun run scripts/generate-plugin-tree.ts
 *     --out plugin`)
 *   - scripts/check-plugin-tree.sh: regenerates into a tmpdir and byte-diffs
 *     against the committed tree (drift gate, runs in `bun run verify` + CI)
 *   - .github/workflows/release.yml `publish-codex-plugin` job: publishes the
 *     tree + plugin manifests + launcher to the `codex-plugin` orphan branch.
 *
 * Curation model (one publication decision per lane, review-visible):
 *   lane set = (openclaw.plugin.json#skills ∖ base_exclusions) ∪ additions
 * where additions/base_exclusions live in skills/plugin-lanes.json with a
 * reason per entry. Shared deps (skills/conventions/, skills/_*.md and
 * _brain-filing-rules.json) always ship, mirroring the openclaw bundler.
 *
 * Starter-surface gap snapshot: each bundled skill's frontmatter `tools:`
 * list is compared against the PLUGIN_SURFACE op set (the plugin lanes
 * serve `--surface full` today, the surface every stdio registration gbrain
 * writes pins; the root plugin manifests must pin the same value). Harness tools (shell/exec/read/write/edit/
 * web_search/web_fetch), literal `gbrain` (CLI usage marker), and unknown
 * non-op names are not MCP ops; `mcp:`-prefixed names count with the prefix
 * stripped. The computed per-skill gap set must equal the `starter_gaps`
 * snapshot recorded in skills/plugin-lanes.json — a new beyond-starter op is
 * a conscious, review-visible curation event, not silent drift. Refresh the
 * snapshot with --write-gaps.
 *
 * Usage:
 *   bun run scripts/generate-plugin-tree.ts --out <dir> [--write-gaps]
 *
 * Prints the sorted relative file list to stdout; diagnostics to stderr.
 * Exit codes: 0 ok, 1 curation/gap violation, 2 usage error.
 */

import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
import { join, resolve } from 'path';
import { allowedOpNames } from '../src/mcp/surface.ts';
import { PLUGIN_SURFACE } from '../src/core/mcp-registration.ts';
import { operations } from '../src/core/operations.ts';
import { cliEquivalent } from '../src/core/ops/cli-equivalent.ts';
import { parseSkillFrontmatter } from '../src/core/skill-frontmatter.ts';
import { FAILSAFE_SCHEMA, load } from 'js-yaml';
// Personas: the SINGLE validation implementation (the harness-bridge CLI
// imports the same module), so CLI errors and CI errors match by construction.
import { loadPersonas, type PersonaDef } from '../src/core/skillpack/personas.ts';
import { INSTALL_PIN } from '../src/core/install-ref.ts';

// GBRAIN_PLUGIN_TREE_ROOT is the negative-fixture test seam: the manifest
// test points the generator at a synthetic repo root to prove each curation
// violation actually fails (a guard that cannot fail is not coverage).
const ROOT = process.env.GBRAIN_PLUGIN_TREE_ROOT || resolve(import.meta.dir, '..');

function usage(): never {
  console.error(
    'usage: bun run scripts/generate-plugin-tree.ts --out <dir> [--variants-out <dir>] [--write-gaps]',
  );
  process.exit(2);
}

const args = process.argv.slice(2);
let out = '';
let variantsOut = '';
let writeGaps = false;
for (let i = 0; i < args.length; i++) {
  const a = args[i];
  if (a === '--out') out = args[++i] ?? '';
  else if (a === '--variants-out') variantsOut = args[++i] ?? '';
  else if (a === '--write-gaps') writeGaps = true;
  else usage();
}
if (!out) usage();

interface PluginLanes {
  starter_policy: string;
  additions: Record<string, string>;
  base_exclusions: Record<string, string>;
  not_added: Record<string, string>;
  /** Persona curation (validated by src/core/skillpack/personas.ts). The
   *  --write-gaps writer MUST spread-preserve this block — pinned by a
   *  byte-identical round-trip test. */
  personas?: Record<string, PersonaDef>;
  starter_gaps: Record<string, string[]>;
}

const openclaw = JSON.parse(readFileSync(join(ROOT, 'openclaw.plugin.json'), 'utf8')) as {
  skills: string[];
};
const lanesPath = join(ROOT, 'skills', 'plugin-lanes.json');
const lanes = JSON.parse(readFileSync(lanesPath, 'utf8')) as PluginLanes;
const manifest = JSON.parse(readFileSync(join(ROOT, 'skills', 'manifest.json'), 'utf8')) as {
  skills: { name: string }[];
};
const manifestNames = new Set(manifest.skills.map(s => s.name));

const base = openclaw.skills.map(s => s.replace(/^skills\//, ''));
const baseSet = new Set(base);
let failed = false;
const fail = (msg: string) => {
  console.error(`generate-plugin-tree: ${msg}`);
  failed = true;
};

// ── Curation-record validation ──────────────────────────────────────────────
for (const slug of Object.keys(lanes.additions)) {
  if (baseSet.has(slug)) fail(`addition '${slug}' is already in the openclaw base — remove from additions`);
  if (!manifestNames.has(slug)) fail(`addition '${slug}' is not in skills/manifest.json`);
  if (!existsSync(join(ROOT, 'skills', slug, 'SKILL.md'))) fail(`addition '${slug}' has no skills/${slug}/SKILL.md`);
  if (slug in lanes.base_exclusions || slug in lanes.not_added) fail(`'${slug}' appears in additions AND an exclusion record`);
}
for (const slug of Object.keys(lanes.base_exclusions)) {
  if (!baseSet.has(slug)) fail(`base_exclusion '${slug}' is not in the openclaw base — stale record`);
  if (slug in lanes.not_added) fail(`'${slug}' appears in BOTH base_exclusions and not_added`);
}
for (const [slug, reason] of [...Object.entries(lanes.additions), ...Object.entries(lanes.base_exclusions), ...Object.entries(lanes.not_added)]) {
  if (typeof reason !== 'string' || reason.length < 10) fail(`'${slug}' needs a real reason (>=10 chars)`);
}

const laneSet = [
  ...base.filter(s => !(s in lanes.base_exclusions)),
  ...Object.keys(lanes.additions),
].sort();

// ── Persona validation (single implementation: src/core/skillpack/personas.ts)
let personas: Record<string, PersonaDef> = {};
try {
  personas = loadPersonas(ROOT).personas;
} catch (err) {
  fail((err as Error).message);
}

// ── Starter-gap snapshot ────────────────────────────────────────────────────
const SURFACE_OPS = allowedOpNames(operations, PLUGIN_SURFACE);
// Harness-native tool names a skill may declare that are not gbrain MCP ops.
const HARNESS_TOOLS = new Set(['shell', 'exec', 'read', 'write', 'edit', 'web_search', 'web_fetch', 'gbrain']);

function frontmatterTools(slug: string): string[] {
  // Canonical parser (src/core/skill-frontmatter.ts) — handles BOTH the
  // inline (`tools: [a, b]`) and block-list YAML forms; a hand-rolled
  // block-only parser here would silently drop gaps if a skill switched to
  // the inline form (the exact drift the starter_gaps snapshot exists to
  // catch).
  const text = readFileSync(join(ROOT, 'skills', slug, 'SKILL.md'), 'utf8');
  return parseSkillFrontmatter(text)?.tools ?? [];
}

/** The beyond-starter MCP ops a bundled skill declares (sorted). */
function starterGaps(slug: string): string[] {
  const mcpOps = frontmatterTools(slug)
    .map(t => (t.startsWith('mcp:') ? t.slice(4) : t))
    // Multi-word entries ("gbrain schema add-type …") are CLI command
    // strings, not MCP op names — same class as the bare `gbrain` marker.
    .filter(t => !HARNESS_TOOLS.has(t) && !t.startsWith('gbrain '));
  return [...new Set(mcpOps.filter(t => !SURFACE_OPS.has(t)))].sort();
}

const computedGaps: Record<string, string[]> = {};
for (const slug of laneSet) {
  const gaps = starterGaps(slug);
  if (gaps.length > 0) computedGaps[slug] = gaps;
}

/**
 * Agent contract v1 (F6): the generated copy of a skill whose steps name
 * tools outside the plugin's starter surface ends with a note mapping each
 * one to its gbrain CLI equivalent. Source skills are never edited.
 */
const OPS_BY_NAME = new Map(operations.map(op => [op.name, op]));
function surfaceNote(gaps: readonly string[]): string {
  const rows = gaps.map(name => {
    const op = OPS_BY_NAME.get(name);
    return `- \`${name}\` → \`${op ? cliEquivalent(op).join(' ') : `gbrain call ${name} '<params_json>'`}\``;
  });
  return [
    '', '## Tools outside your MCP surface', '',
    `This plugin serves the ${PLUGIN_SURFACE} tool surface. When a step above names one of these tools and your tool list`,
    'does not have it, call request_tools {"surface":"full"} to add it to this session, or run its gbrain CLI equivalent:', '',
    ...rows, '',
    "To widen every new session, set this machine's plugin surface with GBRAIN_SURFACE=full.", '',
  ].join('\n');
}

/** Claude Code's skill listing caps description + when_to_use at this many characters per skill. */
const SKILL_LISTING_CHARS = 1536;
const WHEN_TO_USE_TRIGGERS = 5;

/**
 * #5858: Claude Code lists a skill by `name`, `description` and `when_to_use`
 * only, so `triggers:` never reached the model. Each plugin-lane SKILL.md
 * that declares triggers and no `when_to_use` gets one built from its first
 * triggers, kept inside the listing cap. Source skills stay unchanged.
 */
function withWhenToUse(text: string): string {
  const fm = parseSkillFrontmatter(text);
  const triggers = (fm?.triggers ?? []).filter(t => t.trim());
  if (!fm || triggers.length === 0 || /^when_to_use:/m.test(fm.raw)) return text;
  let description = '';
  try {
    const data: unknown = load(fm.raw, { schema: FAILSAFE_SCHEMA });
    if (data && typeof data === 'object' && typeof (data as { description?: unknown }).description === 'string') description = (data as { description: string }).description;
  } catch { return text; }
  const room = SKILL_LISTING_CHARS - description.length - 1;
  let picked = triggers.slice(0, WHEN_TO_USE_TRIGGERS);
  const render = (list: string[]) => `Use when the user asks: ${list.map(t => `"${t.trim()}"`).join(', ')}.`;
  while (picked.length > 1 && render(picked).length > room) picked = picked.slice(0, -1);
  if (render(picked).length > room) return text;
  const close = text.indexOf('\n---', 4);
  return `${text.slice(0, close)}\nwhen_to_use: ${JSON.stringify(render(picked))}${text.slice(close)}`;
}

/** Copy one bundled skill; add `when_to_use` and append the surface note to its SKILL.md when it has gaps. */
function copySkill(slug: string, destSkillsDir: string): void {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  cpSync(join(ROOT, 'skills', slug), join(destSkillsDir, slug), { recursive: true });
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator; slug comes from this repository's own plugin definition
  const skillMd = join(destSkillsDir, slug, 'SKILL.md');
  const gaps = starterGaps(slug);
  const text = withWhenToUse(readFileSync(skillMd, 'utf8'));
  writeFileSync(skillMd, gaps.length === 0 ? text : text.replace(/\n*$/, '\n') + surfaceNote(gaps));
}

if (writeGaps) {
  const next: PluginLanes = { ...lanes, starter_gaps: computedGaps };
  writeFileSync(lanesPath, JSON.stringify(next, null, 2) + '\n');
  console.error(`generate-plugin-tree: wrote starter_gaps snapshot (${Object.keys(computedGaps).length} skills with gaps)`);
} else {
  const recorded = JSON.stringify(lanes.starter_gaps ?? {});
  const computed = JSON.stringify(computedGaps);
  if (recorded !== computed) {
    fail(
      'starter_gaps snapshot in skills/plugin-lanes.json is stale — a bundled skill now ' +
        'declares different beyond-starter MCP ops. Review the change, then refresh with ' +
        '`bun run scripts/generate-plugin-tree.ts --out plugin --write-gaps`.',
    );
  }
}

// The root plugin manifests (copied into every variant) must pin the plugin surface.
function pinnedSurface(args: unknown): string | undefined {
  if (!Array.isArray(args)) return undefined;
  const i = args.indexOf('--surface');
  return i >= 0 ? String(args[i + 1]) : undefined;
}
for (const file of ['.codex-plugin/mcp.json', '.claude-plugin/plugin.json']) {
  if (!existsSync(join(ROOT, file))) continue;
  const servers = (JSON.parse(readFileSync(join(ROOT, file), 'utf8')) as { mcpServers?: Record<string, { args?: unknown }> }).mcpServers;
  const pinned = pinnedSurface(servers?.gbrain?.args);
  if (pinned !== PLUGIN_SURFACE) fail(`${file} pins --surface ${pinned ?? '(none)'}; plugin lanes serve the plugin surface '${PLUGIN_SURFACE}' (src/core/mcp-registration.ts)`);
}

if (failed) process.exit(1);

// ── Emit the tree ───────────────────────────────────────────────────────────
const outDir = resolve(out);
rmSync(outDir, { recursive: true, force: true });
mkdirSync(join(outDir, 'skills'), { recursive: true });

/**
 * Shared deps: always ship (mirrors openclaw.plugin.json#shared_deps). ONE
 * implementation for the main tree and every persona variant — the two copy
 * sites must never diverge (the shared_deps reconciliation follow-up in
 * TODOS.md gets fixed in one place).
 */
// Semgrep path-join suppressions in this file: repo-only build/CI tooling,
// deliberately not wired into src/cli.ts. ROOT is the repo root (or the
// test-seam env var our own manifest test sets), persona names come from the
// committed skills/plugin-lanes.json via loadPersonas validation, and
// --out/--variants-out are operator flags with their own refuse() guards —
// there is no untrusted input in these paths.
function copySharedDeps(destSkillsDir: string): void {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  cpSync(join(ROOT, 'skills', 'conventions'), join(destSkillsDir, 'conventions'), { recursive: true });
  for (const f of readdirSync(join(ROOT, 'skills'))) {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    if (/^_.*\.(md|json)$/.test(f)) cpSync(join(ROOT, 'skills', f), join(destSkillsDir, f));
  }
}

for (const slug of laneSet) {
  copySkill(slug, join(outDir, 'skills'));
}
copySharedDeps(join(outDir, 'skills'));

const version = readFileSync(join(ROOT, 'VERSION'), 'utf8').trim();
const gapSkills = Object.keys(computedGaps).length;
writeFileSync(
  join(outDir, 'README.md'),
  `<!-- gbrain-plugin-tree-stamp: ${version} -->
# gbrain plugin skill tree (generated — do not hand-edit)

This tree is the curated skill set for the gbrain Codex and Claude Code
plugins. Regenerate with \`bun run scripts/generate-plugin-tree.ts --out plugin\`;
curation lives in \`skills/plugin-lanes.json\` (one recorded decision per
addition/exclusion).

## MCP surface note (read once)

The plugin's MCP server runs \`gbrain serve --surface ${PLUGIN_SURFACE}\` — ${SURFACE_OPS.size}
operations, the same surface every stdio registration gbrain writes pins.
${gapSkills === 0
    ? `Every gbrain operation the bundled skills name is on it. A harness that caps
its tool count can narrow this machine's plugin surface with
\`GBRAIN_SURFACE=starter\` (or \`verbs\`); the server honors it and new sessions
pick it up. Skills keep their first-class \`gbrain\` CLI paths for anything a
narrowed list leaves out.`
    : `${gapSkills} bundled skills reference gbrain operations beyond that surface; every one of
them has a first-class \`gbrain\` CLI path, which is the primary way skills
drive gbrain. When a skill step names an operation your MCP tool list doesn't
carry, call \`request_tools {"surface":"full"}\` to add it to this session, run
the equivalent \`gbrain\` CLI command, or widen this machine's plugin surface
with \`GBRAIN_SURFACE=full\` (the server honors it; new sessions pick it up).`}

## Requirements

- gbrain CLI installed: \`bun install -g ${INSTALL_PIN}\`
  (the npm package named \`gbrain\` is unrelated — never \`npm install -g gbrain\`).
- A brain: \`gbrain init\` (the bundled \`setup\` skill walks the full path).
`,
);

// ── Persona variant trees (marketplace entries gbrain-coding / gbrain-daily) ─
// Each variant root is SELF-CONTAINED (Claude Code installs the plugin source
// dir only): its own generated .claude-plugin/plugin.json + .codex-plugin/
// manifests (version from VERSION → variant lockstep is automatic under the
// byte-diff drift gate), a byte-copy of the launcher, the persona's skills,
// and the same shared-dep set the main tree ships.
function emitVariant(variantsDir: string, personaName: string, def: PersonaDef, version: string): void {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  const root = join(variantsDir, def.plugin_name);
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  mkdirSync(join(root, 'skills'), { recursive: true });

  const slugs = Object.keys(def.skills).sort();
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own plugin definition
  for (const slug of slugs) copySkill(slug, join(root, 'skills'));
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  copySharedDeps(join(root, 'skills'));

  // Launcher byte-copy (cpSync preserves the executable bit).
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  cpSync(join(ROOT, '.agents', 'gbrain-launcher'), join(root, '.agents', 'gbrain-launcher'));

  // The per-turn hook names its plugin (GBRAIN_PLUGIN) so that, with several
  // gbrain plugins enabled, the CLI runs only the highest-precedence one's
  // (pluginHookYields, src/core/bootstrap/plugin-lanes.ts).
  const LANE = 'env GBRAIN_HOOK_LANE=plugin ';
  const withIdentity = (hooks: unknown): unknown => {
    const text = JSON.stringify(hooks);
    if (!/^[a-z0-9-]+$/.test(def.plugin_name) || !text?.includes(LANE)) {
      console.error(`generate-plugin-tree: cannot name ${def.plugin_name} in the root manifests' hook commands (expected "${LANE}…")`);
      process.exit(1);
    }
    return JSON.parse(text.replaceAll(LANE, `${LANE}GBRAIN_PLUGIN=${def.plugin_name} `));
  };

  // Claude plugin manifest: model on the root manifest, retargeted at the
  // variant root (skills live at ./skills/ here, not ./plugin/skills/).
  const claudeBase = JSON.parse(readFileSync(join(ROOT, '.claude-plugin', 'plugin.json'), 'utf8')) as Record<
    string,
    unknown
  >;
  const claudeVariant = {
    ...claudeBase,
    name: def.plugin_name,
    version,
    description: `${def.description} (persona variant of the gbrain plugin — ${slugs.length} skills)`,
    skills: './skills/',
    hooks: withIdentity(claudeBase.hooks),
  };
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  mkdirSync(join(root, '.claude-plugin'), { recursive: true });
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  writeFileSync(join(root, '.claude-plugin', 'plugin.json'), JSON.stringify(claudeVariant, null, 2) + '\n');

  // Codex plugin manifest + mcp.json: same retarget; mcp.json is verbatim
  // (its paths are already variant-root-relative: ./.agents/gbrain-launcher).
  const codexBase = JSON.parse(readFileSync(join(ROOT, '.codex-plugin', 'plugin.json'), 'utf8')) as Record<
    string,
    unknown
  >;
  const codexVariant = {
    ...codexBase,
    name: def.plugin_name,
    version,
    description: `${def.description} (persona variant of the gbrain plugin — ${slugs.length} skills)`,
    skills: './skills/',
    mcpServers: './.codex-plugin/mcp.json',
    hooks: withIdentity(codexBase.hooks),
  };
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  mkdirSync(join(root, '.codex-plugin'), { recursive: true });
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  writeFileSync(join(root, '.codex-plugin', 'plugin.json'), JSON.stringify(codexVariant, null, 2) + '\n');
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  cpSync(join(ROOT, '.codex-plugin', 'mcp.json'), join(root, '.codex-plugin', 'mcp.json'));

  writeFileSync(
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    join(root, 'README.md'),
    `<!-- gbrain-plugin-tree-stamp: ${version} -->
# ${def.plugin_name} (generated persona variant — do not hand-edit)

${def.description}

${slugs.length} skills curated from the gbrain plugin lane (persona
\`${personaName}\` in \`skills/plugin-lanes.json#personas\`, one recorded
reason per skill). Install exactly ONE gbrain plugin per machine — every
variant serves the same \`gbrain\` MCP server name, so two installed variants
would double-serve. The full-lane plugin's README carries the MCP surface
note; it applies verbatim here.

Regenerate with \`bun run scripts/generate-plugin-tree.ts --out plugin
--variants-out plugin-variants\`.
`,
  );
}

if (variantsOut) {
  const variantsDir = resolve(variantsOut);
  // rmSync guard: --variants-out is recursively DELETED before emission, so
  // a mistyped path must refuse rather than eat a real directory. Refuse:
  // filesystem root, the repo root or any ancestor of it, the --out dir, and
  // any existing NON-generated non-empty dir (a prior emission is
  // recognizable by a variant README carrying the tree stamp).
  const refuse = (why: string): never => {
    console.error(`generate-plugin-tree: refusing --variants-out ${variantsDir}: ${why}`);
    process.exit(2);
  };
  if (variantsDir === '/' || variantsDir === resolve(out)) refuse('unsafe target');
  if (ROOT === variantsDir || ROOT.startsWith(variantsDir + '/')) refuse('would delete the repo root');
  if (existsSync(variantsDir) && readdirSync(variantsDir).length > 0) {
    const looksGenerated = readdirSync(variantsDir).some(d => {
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      const readme = join(variantsDir, d, 'README.md');
      try {
        return existsSync(readme) && readFileSync(readme, 'utf8').includes('gbrain-plugin-tree-stamp');
      } catch {
        return false;
      }
    });
    if (!looksGenerated) refuse('existing non-empty directory without a generated tree stamp');
  }
  rmSync(variantsDir, { recursive: true, force: true });
  const version = readFileSync(join(ROOT, 'VERSION'), 'utf8').trim();
  for (const [personaName, def] of Object.entries(personas)) {
    emitVariant(variantsDir, personaName, def, version);
  }
  console.error(
    `generate-plugin-tree: ${Object.keys(personas).length} persona variant(s) → ${variantsDir}`,
  );
}

// Print sorted relative file list (parity with generate-template-repo.ts).
const files: string[] = [];
const walk = (dir: string, rel: string) => {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const r = rel ? `${rel}/${entry.name}` : entry.name;
    if (entry.isDirectory()) walk(join(dir, entry.name), r);
    else files.push(r);
  }
};
walk(outDir, '');
for (const f of files.sort()) console.log(f);
console.error(`generate-plugin-tree: ${laneSet.length} skills, ${files.length} files → ${outDir}`);