fde2e-bu 0.0.0 → 1.3.0

package/src/skills/frontmatter.mjs

@@ -0,0 +1,150 @@
+// SKILL.md frontmatter 解析器（task 2.1/2.2）——手写最小 YAML 子集，不引 yaml 依赖
+// （零依赖原则；agentskills.io frontmatter 实际用到的语法面极小：
+//   顶层标量键值 + 一~两层嵌套 map + 行内 flow 数组，足够覆盖 name/description/
+//   version/metadata.version 的渐进披露读取）。
+//
+// 支持的子集：
+//   key: value            标量（裸值 / 单引号 / 双引号字符串；行尾 " #" 注释）
+//   key:                  空值或嵌套块（下一行更深缩进 → 子 map）
+//   key: [a, b, c]        行内 flow 数组（字符串元素；引号内逗号不切分——r1 状态机）
+//   键字符＝\w＋CJK＋.-（r1：允许非 ASCII 键，如 `名称:`）
+//   '#' 开头整行注释、空行跳过
+// 其余（多行字符串|、锚点、复杂 flow 等）报 PARSE_ERROR——渐进披露不需要。
+
+/** @returns {{ ok: true, data: Record<string, unknown> } | { ok: false, reason: string }} */
+export function parseFrontmatter(text) {
+  if (typeof text !== 'string') return { ok: false, reason: '输入不是字符串' };
+  const lines = text.split('\n').map((l) => l.replace(/\r$/, ''));
+  if (lines[0] === undefined || lines[0].trim() !== '---') {
+    return { ok: false, reason: '首行不是 --- 分隔符（无 frontmatter）' };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (t === '---' || t === '...') { end = i; break; }
+    if (t === '') continue; // 分隔符前允许空行
+  }
+  if (end === -1) return { ok: false, reason: 'frontmatter 未闭合（缺第二个 --- 行）' };
+  try {
+    return { ok: true, data: parseYamlSubset(lines.slice(1, end)) };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+const indentOf = (s) => { const m = /^ */.exec(s); return m ? m[0].length : 0; };
+const isSignificant = (l) => l.trim() !== '' && !l.trim().startsWith('#');
+
+/** 标量解析：剥引号（支持双/单引号与 \" 转义）、剥行尾注释；一律返回字符串。 */
+function parseScalar(raw) {
+  let s = raw.trim();
+  if (s.startsWith('"')) {
+    const m = /^"((?:[^"\\]|\\.)*)"/.exec(s);
+    if (!m) throw new Error(`双引号字符串未闭合：${raw}`);
+    return m[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  if (s.startsWith("'")) {
+    const m = /^'([^']*)'/.exec(s);
+    if (!m) throw new Error(`单引号字符串未闭合：${raw}`);
+    return m[1];
+  }
+  const hash = s.indexOf(' #');
+  if (hash !== -1) s = s.slice(0, hash).trim(); // 行尾注释（裸值才会出现 " #"）
+  return s;
+}
+
+/** 行内 flow 数组：[a, "b", 'c'] → string[]。
+ *  r1：逗号切分走引号状态机——引号内的逗号（如 tags: ["a,b", c]）不得切开。 */
+function parseFlowArray(raw) {
+  const s = raw.trim();
+  if (!s.endsWith(']')) throw new Error(`flow 数组未闭合：${raw}`);
+  const inner = s.slice(1, -1).trim();
+  if (inner === '') return [];
+  return splitFlowElements(inner).map((el) => parseScalar(el));
+}
+
+/** 引号保护切分：单/双引号内的分隔符与转义（\"）原样保留，引号外逗号才分段。 */
+function splitFlowElements(inner) {
+  const parts = [];
+  let cur = '';
+  let quote = null; // null | '"' | "'"
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote !== null) {
+      cur += ch;
+      if (ch === '\\' && quote === '"' && i + 1 < inner.length) { cur += inner[++i]; continue; }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue; }
+    if (ch === ',') { parts.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts.map((p) => p.trim()).filter((p) => p !== '');
+}
+
+/**
+ * 缩进递归下降解析（行数组 → 普通对象）。
+ * @param {string[]} lines
+ * @param {number} [baseIndent] 当前块基准缩进
+ */
+function parseYamlSubset(lines, baseIndent = 0) {
+  const map = {};
+  let i = 0;
+  const nextSignificant = (from) => {
+    for (let j = from; j < lines.length; j++) if (isSignificant(lines[j])) return j;
+    return -1;
+  };
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!isSignificant(line)) { i++; continue; }
+    const ind = indentOf(line);
+    if (ind < baseIndent) break;
+    if (ind > baseIndent) throw new Error(`意外缩进（无宿主键）：${line.trim()}`);
+    // r1：键允许非 ASCII（技能作者用中文键，如 `名称: …`）；\w＝[A-Za-z0-9_]，另放行 CJK 与 .-
+    const m = /^([\w\u4e00-\u9fff.-]+):\s*(.*)$/.exec(line.trim());
+    if (!m) throw new Error(`无法解析的 frontmatter 行：${line.trim()}`);
+    const key = m[1];
+    const rest = m[2];
+    if (rest === '') {
+      const nxt = nextSignificant(i + 1);
+      if (nxt !== -1 && indentOf(lines[nxt]) > baseIndent) {
+        map[key] = parseYamlSubset(lines.slice(nxt), indentOf(lines[nxt]));
+        // 块值消费到「下一行首」——continue 免得多跳一行（nxt+count 已指向未消费行）
+        i = nxt + countConsumed(lines, nxt, indentOf(lines[nxt]));
+        continue;
+      }
+      map[key] = null;
+    } else if (rest.trim().startsWith('[')) {
+      map[key] = parseFlowArray(rest);
+    } else {
+      map[key] = parseScalar(rest);
+    }
+    i++;
+  }
+  return map;
+}
+
+/** 子块被递归解析后，计算其在原数组中占用的行数（到下一个不缩进行或末尾）。 */
+function countConsumed(lines, start, childIndent) {
+  let n = 0;
+  for (let j = start; j < lines.length; j++) {
+    if (isSignificant(lines[j]) && indentOf(lines[j]) < childIndent) break;
+    n++;
+  }
+  return n;
+}
+
+/** 渐进披露取值：version 取顶层，缺失回落 metadata.version（agentskills 规范位置）。 */
+export function disclosedFields(data) {
+  const metadata = data && typeof data.metadata === 'object' && data.metadata !== null ? data.metadata : {};
+  return {
+    name: typeof data?.name === 'string' ? data.name : '',
+    description: typeof data?.description === 'string' ? data.description : '',
+    version:
+      typeof data?.version === 'string' && data.version !== '' ? data.version
+        : typeof metadata.version === 'string' && metadata.version !== '' ? metadata.version
+          : '',
+  };
+}

package/src/skills/skills.mjs

@@ -0,0 +1,323 @@
+// fde2e-bu skills —— 技能包管理（tasks 2.1/2.2/2.3）。
+// 事实标准 agentskills.io：<skill>/SKILL.md + name/description 前置渐进披露；
+// 目录约定收敛 .agents/skills（默认写），兼容 .claude/skills。
+import { existsSync, readdirSync, readFileSync, statSync, realpathSync, rmSync, renameSync, mkdirSync, cpSync, mkdtempSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, dirname, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { parse, UsageError, assertFlags, assertNoPositionals } from '../args.mjs';
+import { parseFrontmatter, disclosedFields } from './frontmatter.mjs';
+
+export const SKILL_FILE = 'SKILL.md';
+export const DEST_DIRS = { agents: '.agents/skills', claude: '.claude/skills' };
+
+/** 非法技能名（r1 P0-1）：exit 1。路径穿越/分隔符/绝对路径在此全被拒。 */
+export class IllegalSkillNameError extends Error {
+  constructor(name) {
+    super(`非法技能名：${name}（须为小写字母数字连字符，且不得含路径分隔符/…/绝对路径）`);
+    this.name = 'IllegalSkillNameError';
+  }
+}
+
+/** containment 判定：target 是否仍在 base 目录内（path.relative 不以 .. 开头且非绝对）。
+ *  双保险防线——NAME_RE 已拒穿越形状，此函数兜住未来重构引入的绕过。 */
+export function isContained(base, target) {
+  const rel = relative(resolve(base), resolve(target));
+  return !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+// C1 flag 面（P2-6）：按子命令收窄——`skills list --force` 这类此前被解析后静默
+// 忽略的组合，现在一律用法错误 exit 2。validate 接受位置参数（待校验路径），
+// list 不接受（本工作区扫描）。
+const SUB_OPTIONS = {
+  list: { json: { type: 'boolean' }, root: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+  add: { dest: { type: 'string' }, skill: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+  remove: { dest: { type: 'string' }, all: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+  validate: { help: { type: 'boolean', short: 'h' } },
+};
+const SUB_FLAGS = {
+  list: ['json', 'root', 'help'],
+  add: ['dest', 'skill', 'force', 'help'],
+  remove: ['dest', 'all', 'help'],
+  validate: ['help'],
+};
+
+/** 从 startDir 逐级向上找最近的含 .agents/skills 或 .claude/skills 的目录。 */
+export function findSkillsWorkspace(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const roots = Object.entries(DEST_DIRS)
+      .filter(([, rel]) => isDir(join(dir, rel)))
+      .map(([name, rel]) => ({ name, path: join(dir, rel), workspace: dir }));
+    if (roots.length > 0) return { workspace: dir, roots };
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { workspace: null, roots: [] };
+}
+
+const isDir = (p) => existsSync(p) && statSync(p).isDirectory();
+
+/** 单个技能目录 → 渐进披露条目（只读 frontmatter，不读正文）。 */
+export function readSkillEntry(rootName, skillDir) {
+  const file = join(skillDir, SKILL_FILE);
+  const entry = { source: rootName, dir: skillDir, name: basename(skillDir), version: '', description: '', error: null };
+  if (!existsSync(file)) {
+    entry.error = '缺 SKILL.md';
+    return entry;
+  }
+  const parsed = parseFrontmatter(readFileSync(file, 'utf8'));
+  if (!parsed.ok) {
+    entry.error = `frontmatter 解析失败：${parsed.reason}`;
+    return entry;
+  }
+  const f = disclosedFields(parsed.data);
+  entry.name = f.name || entry.name;
+  entry.description = f.description;
+  entry.version = f.version;
+  return entry;
+}
+
+/** 扫描全部技能（list/validate 共用）。 */
+export function scanSkills(startDir) {
+  const { workspace, roots } = findSkillsWorkspace(startDir);
+  const skills = [];
+  for (const root of roots) {
+    for (const ent of readdirSync(root.path, { withFileTypes: true })) {
+      if (!ent.isDirectory() || ent.name.startsWith('.') || ent.name === 'node_modules') continue;
+      skills.push(readSkillEntry(root.name, join(root.path, ent.name)));
+    }
+  }
+  return { workspace, roots, skills };
+}
+
+// ---------- validate（task 2.3） ----------
+
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** agentskills.io 规则集 → { pass, failures: string[] }。
+ * dirNameCheck＝是否校验 name＝目录名（安装后布局约束）；add 源校验时关闭——
+ * 源目录名（临时克隆/重命名）可合法异于 name，安装以 name 建目录、一致性由构造保证。 */
+export function validateSkillDir(skillDir, { dirNameCheck = true } = {}) {
+  const failures = [];
+  const file = join(skillDir, SKILL_FILE);
+  if (!existsSync(file)) return { pass: false, failures: ['缺 SKILL.md'] };
+  const parsed = parseFrontmatter(readFileSync(file, 'utf8'));
+  if (!parsed.ok) return { pass: false, failures: [`frontmatter 解析失败：${parsed.reason}`] };
+  const { name, description } = disclosedFields(parsed.data);
+  if (!name) failures.push('name 缺失');
+  else {
+    if (name.length > 64) failures.push(`name 超长（${name.length} > 64）`);
+    if (!NAME_RE.test(name)) failures.push(`name 不合小写连字符规则：${name}`);
+    if (dirNameCheck && name !== basename(resolve(skillDir))) failures.push(`name（${name}）≠ 目录名（${basename(resolve(skillDir))}）`);
+  }
+  if (!description) failures.push('description 缺失');
+  else if (description.length > 1024) failures.push(`description 超长（${description.length} > 1024）`);
+  return { pass: failures.length === 0, failures };
+}
+
+function runValidate(positionals, values) {
+  // r1 P1-1：map 回调透传 (v,i,arr) 给 resolve 会被当多参 join 解析——必须单参显式包一层
+  const targets = positionals.length > 0 ? positionals.map((p) => resolve(p)) : null;
+  let results;
+  if (targets) {
+    results = targets.map((dir) => ({ dir, ...validateSkillDir(dir) }));
+  } else {
+    const { skills } = scanSkills(process.cwd());
+    if (skills.length === 0) {
+      console.log('未发现技能目录（向上未找到 .agents/skills / .claude/skills，或目录为空）');
+      return 0;
+    }
+    results = skills.map((s) => ({ dir: s.dir, ...validateSkillDir(s.dir) }));
+  }
+  let failed = 0;
+  for (const r of results) {
+    if (r.pass) console.log(`PASS ${r.dir}`);
+    else {
+      failed++;
+      console.error(`FAIL ${r.dir}`);
+      for (const f of r.failures) console.error(`  - ${f}`);
+    }
+  }
+  console.log(`校验 ${results.length} 个技能：${results.length - failed} 通过 / ${failed} 失败`);
+  return failed > 0 ? 1 : 0;
+}
+
+// ---------- list（task 2.1） ----------
+
+function runList(values) {
+  const startDir = values.root ? resolve(String(values.root)) : process.cwd();
+  const { workspace, roots, skills } = scanSkills(startDir);
+  if (values.json) {
+    console.log(JSON.stringify({ workspace, roots: roots.map((r) => r.path), skills }, null, 2));
+    return 0;
+  }
+  if (roots.length === 0) {
+    console.log(`未找到技能目录（自 ${startDir} 向上无 .agents/skills / .claude/skills）`);
+    return 0;
+  }
+  console.log(`工作区：${workspace}`);
+  for (const r of roots) console.log(`目录源：${r.path}（${r.name}）`);
+  if (skills.length === 0) {
+    console.log('（无已装技能）');
+    return 0;
+  }
+  const nameW = Math.max(4, ...skills.map((s) => s.name.length));
+  const verW = Math.max(7, ...skills.map((s) => (s.version || '-').length));
+  console.log(`${'NAME'.padEnd(nameW)}  ${'VERSION'.padEnd(verW)}  SRC  DESCRIPTION`);
+  for (const s of skills) {
+    const desc = (s.error ? `⚠ ${s.error}` : s.description).replace(/\s+/g, ' ');
+    const short = desc.length > 64 ? `${desc.slice(0, 63)}…` : desc;
+    console.log(`${s.name.padEnd(nameW)}  ${(s.version || '-').padEnd(verW)}  ${s.source === 'agents' ? 'ag' : 'cl'}  ${short}`);
+  }
+  return 0;
+}
+
+// ---------- add / remove（task 2.2） ----------
+
+const COPY_EXCLUDE = new Set(['.git', 'node_modules', '__pycache__', '.DS_Store']);
+
+/** 拷贝安装（r1 P1-2：目标已存在时先拷临时目录、成功后再 rm+mv 原子替换——
+ *  中断不丢既有安装；EXDEV 时退回 cp 覆盖）。 */
+function installSkill(srcDir, target) {
+  const copyOpts = { recursive: true, filter: (s) => !COPY_EXCLUDE.has(basename(s)) };
+  if (isDir(target)) {
+    const staging = mkdtempSync(join(tmpdir(), 'fde2e-bu-install-'));
+    try {
+      const staged = join(staging, basename(target));
+      cpSync(srcDir, staged, copyOpts); // 先拷（失败即中止，原安装无损）
+      rmSync(target, { recursive: true, force: true });
+      try {
+        renameSync(staged, target);
+      } catch {
+        // 跨设备 rename（EXDEV 等）：退回 cp（此时旧目标已备份在 staged 失败重来风险窗口最小化）
+        cpSync(staged, target, copyOpts);
+      }
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+    }
+    return;
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  cpSync(srcDir, target, copyOpts);
+}
+
+/** 源解析（r1 item 12）：本地路径直取；git URL 浅克隆到临时目录。
+ *  返回 { dir, cleanup }——cleanup 回收克隆临时目录（调用方 finally 必调）；
+ *  --skill 子目录须 containment 于克隆根内（拒绝 ../../.. 越界与绝对路径）。 */
+function resolveSource(src, skillSub) {
+  if (/^(https?|file):\/\//.test(src)) {
+    const tmp = mkdtempSync(join(tmpdir(), 'fde2e-bu-skill-'));
+    const cleanup = () => rmSync(tmp, { recursive: true, force: true });
+    let dir = tmp;
+    try {
+      if (skillSub) {
+        dir = resolve(tmp, skillSub);
+        if (!isContained(tmp, dir)) throw new IllegalSkillNameError(`--skill ${skillSub}（越出克隆仓库根）`);
+      }
+      try {
+        execFileSync('git', ['clone', '--depth', '1', src, tmp], { stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (err) {
+        throw new Error(`git clone 失败（${src}）：${err.stderr?.toString().trim() || err.message}`);
+      }
+    } catch (err) {
+      cleanup();
+      throw err;
+    }
+    return { dir, cleanup };
+  }
+  return { dir: resolve(src), cleanup: null };
+}
+
+function runAdd(positionals, values) {
+  if (positionals.length !== 1) throw new UsageError('用法：fde2e-bu skills add <src> [--skill <subdir>] [--dest agents|claude] [--force]', { exitCode: 2 });
+  const src = positionals[0];
+  const destName = values.dest ? String(values.dest) : 'agents';
+  if (!(destName in DEST_DIRS)) throw new UsageError(`--dest 取值 agents|claude（收到 ${destName}）`);
+
+  const { dir: srcDir, cleanup } = resolveSource(src, values.skill ? String(values.skill) : undefined);
+  try {
+    if (!isDir(srcDir)) throw new Error(`源不是目录：${srcDir}`);
+    // 源校验关目录名一致性（源目录名可异于 name；安装以 name 建目录）
+    const check = validateSkillDir(srcDir, { dirNameCheck: false });
+    if (!check.pass) {
+      console.error(`源技能未过 validate，拒绝安装：${srcDir}`);
+      for (const f of check.failures) console.error(`  - ${f}`);
+      return 1;
+    }
+    const parsed = parseFrontmatter(readFileSync(join(srcDir, SKILL_FILE), 'utf8'));
+    const { name, version } = disclosedFields(parsed.data);
+
+    // 装载根：向上找既有技能根（保持与 list 同一工作区），找不到落在 cwd
+    const found = findSkillsWorkspace(process.cwd());
+    const workspace = found.workspace ?? process.cwd();
+    const target = join(workspace, DEST_DIRS[destName], name);
+    // r1 P1-2：源即目标（把已装目录当源再 --force）＝自装，先删后拷会把自己删光——拒绝。
+    // realpath 归一比较（macOS /tmp→/private/tmp 符号链接下字符串比较会漏判）
+    const realOf = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+    if (realOf(srcDir) === realOf(target)) {
+      console.error(`源即目标：${srcDir} → ${target}——拒绝自装（如需重装请以原始来源为源）`);
+      return 1;
+    }
+    if (isDir(target) && !values.force) {
+      console.log(`已安装：${name}（${target}）——同名已装不重复安装；--force 覆盖重装`);
+      return 0;
+    }
+    installSkill(srcDir, target);
+    console.log(`已安装：${name}${version ? `@${version}` : ''} → ${target}（源：${src}）`);
+    return 0;
+  } finally {
+    cleanup?.(); // r1 item 12：克隆临时目录必回收
+  }
+}
+
+function runRemove(positionals, values) {
+  if (positionals.length !== 1) throw new UsageError('用法：fde2e-bu skills remove <name> [--dest agents|claude] [--all]', { exitCode: 2 });
+  const name = positionals[0];
+  // r1 P0-1：技能名先过 NAME_RE——`../..`、`..`、绝对路径、含分隔符一律 exit 1，
+  // 不得触碰任何目录（此前 join(base, dest, '../..') 会递归删掉工作区）
+  if (!NAME_RE.test(name)) throw new IllegalSkillNameError(name);
+  const { workspace, roots } = findSkillsWorkspace(process.cwd());
+  const destNames = values.all ? Object.keys(DEST_DIRS) : values.dest ? [String(values.dest)] : roots.map((r) => r.name);
+  const base = workspace ?? process.cwd();
+  let removed = 0;
+  for (const dn of new Set(destNames)) {
+    if (!(dn in DEST_DIRS)) throw new UsageError(`--dest 取值 agents|claude（收到 ${dn}）`);
+    const destRoot = resolve(base, DEST_DIRS[dn]);
+    const target = join(destRoot, name);
+    // r1 P0-1 双保险：即使未来 NAME_RE 放宽，删除目标必须 containment 于技能根内
+    if (!isContained(destRoot, target)) throw new IllegalSkillNameError(name);
+    if (isDir(target)) {
+      rmSync(target, { recursive: true, force: true });
+      console.log(`已移除：${target}`);
+      removed++;
+    }
+  }
+  if (removed === 0) console.log(`未安装：${name}（无 .agents/skills/.claude/skills 下的同名目录）——幂等跳过`);
+  return 0;
+}
+
+// ---------- 组入口 ----------
+
+/** @returns {number} exit code */
+export function cmdSkills(rest) {
+  const [sub, ...subRest] = rest;
+  if (!(sub in SUB_OPTIONS)) {
+    throw new UsageError(`未知子命令：skills ${sub ?? ''}（可用：list/add/remove/validate）`, { exitCode: 2 });
+  }
+  assertFlags(subRest, SUB_FLAGS[sub], `skills ${sub}`);
+  const { positionals, values } = parse(subRest, { options: SUB_OPTIONS[sub] });
+  if (values.help) return 0; // help 文本由 cli.mjs 统一打印（组级 --help 已拦截；此处兜底静默 0）
+  switch (sub) {
+    case 'list': {
+      assertNoPositionals(positionals, 'skills list');
+      return runList(values);
+    }
+    case 'add': return runAdd(positionals, values);
+    case 'remove': return runRemove(positionals, values);
+    case 'validate': return runValidate(positionals, values);
+    default:
+      throw new UsageError(`未知子命令：skills ${sub ?? ''}（可用：list/add/remove/validate）`, { exitCode: 2 });
+  }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};