呼んだはずのスキルが何も返さない — 起動前に名前の解決順序を確定させる

#!/usr/bin/env node
// name-preflight.mjs — スキルの「呼び出し名」を起動前に解決し、衝突を落とす
import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
import { join, basename } from "node:path";
 
// 端末組み込みコマンド。自分の環境の /help 出力から起こし、CI では固定リストとして版管理する
const BUILTIN = new Set([
  "help", "clear", "compact", "config", "cost", "doctor", "exit",
  "init", "login", "logout", "mcp", "memory", "model", "permissions",
  "release-notes", "resume", "review", "rewind", "status", "vim",
]);
 
// 優先度: 数字が小さいほど先に解決される想定。実環境の観測結果で必ず上書きすること
const SOURCES = [
  { id: "project", rank: 1, root: ".claude/skills" },
  { id: "user",    rank: 2, root: join(process.env.HOME ?? "", ".claude/skills") },
  { id: "plugin",  rank: 3, root: ".claude/plugins", nested: true },
];
 
const missingRoots = [];
 
function readName(dir) {
  const f = join(dir, "SKILL.md");
  if (!existsSync(f)) return null;
  const head = readFileSync(f, "utf8").split(/\n---\s*\n/)[0];
  const m = head.match(/^name:\s*(.+)$/m);
  return (m ? m[1] : basename(dir)).trim().replace(/^["']|["']$/g, "");
}
 
function scanFlat(root, source, owner) {
  if (!existsSync(root)) { missingRoots.push(`${source}:${root}`); return []; }
  return readdirSync(root)
    .map((e) => join(root, e))
    .filter((p) => statSync(p).isDirectory())
    .map((p) => ({ name: readName(p), source, owner, path: p }))
    .filter((r) => r.name);
}
 
function collect() {
  const out = [];
  for (const s of SOURCES) {
    if (!s.nested) { out.push(...scanFlat(s.root, s.id, s.id)); continue; }
    if (!existsSync(s.root)) { missingRoots.push(`${s.id}:${s.root}`); continue; }
    for (const plug of readdirSync(s.root)) {
      out.push(...scanFlat(join(s.root, plug, "skills"), s.id, plug));
    }
  }
  return out;
}
 
function resolve(entries) {
  const rank = Object.fromEntries(SOURCES.map((s) => [s.id, s.rank]));
  const byName = new Map();
  for (const e of entries) {
    const list = byName.get(e.name) ?? [];
    list.push(e);
    byName.set(e.name, list);
  }
  const findings = [];
  for (const [name, list] of byName) {
    list.sort((a, b) => rank[a.source] - rank[b.source]);
    const winner = list[0];
    if (BUILTIN.has(name)) {
      findings.push({
        level: "block", name,
        reason: "端末組み込みコマンドと同名。非対話セッションでは呼び出しが解決されない可能性がある",
        effective: "builtin", losers: list,
      });
      continue;
    }
    if (list.length > 1) {
      findings.push({
        level: "warn", name,
        reason: `同名スキルが ${list.length} 件。${winner.source}(${winner.owner}) が優先される`,
        effective: `${winner.source}:${winner.owner}`, losers: list.slice(1),
      });
    }
  }
  return { total: entries.length, unique: byName.size, findings };
}
 
const t0 = process.hrtime.bigint();
const r = resolve(collect());
const ms = Number(process.hrtime.bigint() - t0) / 1e6;
 
const blocks = r.findings.filter((f) => f.level === "block");
const warns  = r.findings.filter((f) => f.level === "warn");
for (const m of missingRoots) console.log(`[GAP] 走査対象が存在しません: ${m}`);
console.log(`scanned=${r.total} unique=${r.unique} block=${blocks.length} warn=${warns.length} in ${ms.toFixed(1)}ms`);
for (const f of [...blocks, ...warns]) {
  console.log(`[${f.level.toUpperCase()}] /${f.name} -> ${f.effective}`);
  console.log(`        ${f.reason}`);
  for (const l of f.losers) console.log(`        shadowed: ${l.source}:${l.owner} (${l.path})`);
}
process.exit(blocks.length > 0 || missingRoots.length > 0 ? 1 : 0);