skillcaddy 0.27.0

package/lib/skillStore.js

@@ -0,0 +1,541 @@
+import {
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  symlink
+} from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { getClaudeStatus } from './claudeStore.js';
+import { buildCollectionSetupAdvice, scanCollectionSetups } from './collectionSetup.js';
+import { getHermesSkillsDir, isHermesEligibleSource, scanHermesSkills } from './hermesStore.js';
+import { normalizeProjectPath, requirePath } from './projectPath.js';
+import { normalizeRoots } from './roots.js';
+import { readSkillMetadata } from './skillMetadata.js';
+import {
+  assertInsideAllowedSkillSources,
+  isInsideAllowedSkillSources,
+  REPOSITORY_SKILLS_FOLDER,
+  REPOSITORY_SKILLS_SOURCE,
+  resolveAllowedSkillSource,
+  SOURCE_FOLDERS,
+  SOURCE_INSTALLING_MARKER,
+  SOURCE_INSTALLING_MARKER_CONTENT
+} from './sourcePolicy.js';
+import { discoverSourceSkillDirectories } from './sourceSkillDiscovery.js';
+import { readSourceRecords } from './sourceRegistry.js';
+import { normalizeEnablementScope } from './enablementScope.js';
+import {
+  linkPathExists,
+  resolveLinkTarget,
+  scanSkillLinks
+} from './skillLinkStore.js';
+
+export async function ensureSourceFolders(roots) {
+  const { libraryRoot, codeRoot } = normalizeRoots(roots);
+
+  await Promise.all(
+    SOURCE_FOLDERS.map((source) => mkdir(path.join(libraryRoot, source), { recursive: true }))
+  );
+
+  // 仓库自带 skills 桶属于代码根。发行形态（npm 包）里它已经存在，
+  // 只读安装目录下创建失败也不应该阻断启动，所以这里吞掉创建错误。
+  await mkdir(path.join(codeRoot, REPOSITORY_SKILLS_FOLDER), { recursive: true }).catch(() => {});
+}
+
+export async function getState(roots, projectPath, { readOnly = false, globalDir, hermesDir } = {}) {
+  const resolvedRoots = normalizeRoots(roots);
+  const { libraryRoot } = resolvedRoots;
+  const safeProjectPath = normalizeProjectPath(projectPath);
+  if (!readOnly) await ensureSourceFolders(resolvedRoots);
+  const skills = await scanSkills(resolvedRoots);
+  const enabled = await scanEnabledSkills(safeProjectPath);
+  const global = (await scanGlobalSkills({ globalDir })).map((skill) => ({
+    ...skill,
+    canDisable: skill.isSymlink && isInsideAllowedSkillSources(resolvedRoots, skill.targetPath)
+  }));
+  const hermes = (await scanHermesSkills({ hermesDir })).map((skill) => ({
+    ...skill,
+    canDisable: skill.isSymlink && isInsideAllowedSkillSources(resolvedRoots, skill.targetPath)
+  }));
+  const setups = await scanCollectionSetups(resolvedRoots, safeProjectPath, skills, enabled);
+  const advice = buildSkillAdvice(resolvedRoots, { skills, enabled, global, hermes, setups });
+  const sources = await readSourceRecords(libraryRoot);
+
+  return {
+    rootDir: libraryRoot,
+    libraryRoot,
+    codeRoot: resolvedRoots.codeRoot,
+    projectPath: safeProjectPath,
+    skills,
+    enabled,
+    global,
+    hermes,
+    setups,
+    advice,
+    sources: buildSourcesInfo(sources),
+    claude: await getClaudeStatus(safeProjectPath),
+    stats: { total: skills.length, enabled: enabled.length, available: skills.filter((skill) => skill.source !== 'archived').length }
+  };
+}
+
+export async function scanSkills(roots) {
+  const resolvedRoots = normalizeRoots(roots);
+  const groups = await Promise.all([
+    scanRepositorySkills(resolvedRoots),
+    ...SOURCE_FOLDERS.map((source) => scanSourceFolder(resolvedRoots, path.join(resolvedRoots.libraryRoot, source), source))
+  ]);
+
+  return groups.flat().sort(compareSkills);
+}
+
+function compareSkills(left, right) {
+  return left.collection.localeCompare(right.collection) || left.name.localeCompare(right.name) || left.id.localeCompare(right.id);
+}
+
+async function scanRepositorySkills(roots) {
+  const sourceDir = path.join(roots.codeRoot, REPOSITORY_SKILLS_FOLDER);
+  return scanSourceFolder(roots, sourceDir, REPOSITORY_SKILLS_SOURCE);
+}
+
+async function scanSourceFolder(roots, sourceDir, source) {
+  const entries = await safeReaddir(sourceDir);
+  const skillGroups = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => scanSourceEntry(roots, source, sourceDir, entry.name))
+  );
+  return skillGroups.flat();
+}
+
+export async function scanEnabledSkills(projectPath) {
+  return scanSkillLinks(getAgentsSkillsDir(normalizeProjectPath(projectPath)));
+}
+
+export async function scanGlobalSkills({ globalDir } = {}) {
+  const directory = getGlobalSkillsDir(globalDir);
+  const skills = await scanSkillLinks(directory);
+  return skills
+    .map((skill) => ({ ...skill, agent: 'Agents', scope: 'global', directory }))
+    .sort((left, right) => left.alias.localeCompare(right.alias));
+}
+
+function buildSkillAdvice(roots, { skills, enabled, global, hermes, setups }) {
+  const advice = buildCollectionSetupAdvice(setups);
+  const availableByName = groupBy(skills.filter((skill) => skill.source !== 'archived'), (skill) => skill.name);
+  const projectByAlias = new Map(enabled.map((skill) => [skill.alias, skill]));
+  const globalByAlias = groupBy(global, (skill) => skill.alias);
+  const hermesByAlias = groupBy(hermes, (skill) => skill.alias);
+
+  for (const skill of enabled) {
+    if (!skill.isSymlink) {
+      advice.push({
+        severity: 'warning',
+        type: 'project-unmanaged-entry',
+        title: `项目存在非软链接 skill：${skill.alias}`,
+        detail: `${skill.linkPath} 不是 Skillcaddy 可安全清理的软链接。启用同名 skill 前请先确认该目录用途。`,
+        alias: skill.alias,
+        path: skill.linkPath
+      });
+      continue;
+    }
+
+    if (!skill.exists) {
+      advice.push({
+        severity: 'warning',
+        type: 'project-broken-link',
+        title: `项目 skill 断链：${skill.alias}`,
+        detail: `${skill.linkPath} 指向不存在的目标：${skill.targetPath}`,
+        alias: skill.alias,
+        path: skill.linkPath,
+        targetPath: skill.targetPath
+      });
+      continue;
+    }
+
+    if (!isInsideAllowedSkillSources(roots, skill.targetPath)) {
+      advice.push({
+        severity: 'info',
+        type: 'project-unmanaged-symlink',
+        title: `项目存在不纳管 skill：${skill.alias}`,
+        detail: `${skill.alias} 指向 Skillcaddy 来源目录之外：${skill.targetPath}`,
+        alias: skill.alias,
+        path: skill.linkPath,
+        targetPath: skill.targetPath
+      });
+    }
+  }
+
+  for (const [alias, globalMatches] of globalByAlias) {
+    const projectSkill = projectByAlias.get(alias);
+    if (projectSkill) {
+      advice.push({
+        severity: 'info',
+        type: 'global-shadowed-by-project',
+        title: `项目 skill 会遮蔽全局 skill：${alias}`,
+        detail: `${alias} 同时存在于项目和全局目录。通常项目级优先，若行为异常请确认 agent 的加载顺序。`,
+        alias,
+        global: globalMatches.map(formatSkillLocation),
+        project: formatSkillLocation(projectSkill)
+      });
+    }
+
+    const availableMatches = availableByName.get(alias) || [];
+    for (const availableSkill of availableMatches) {
+      if (projectSkill?.targetPath === availableSkill.path) continue;
+      if (globalMatches.some((skill) => skill.targetPath === availableSkill.path)) continue;
+      advice.push({
+        severity: 'info',
+        type: 'global-alias-conflict',
+        title: `全局已存在同名 skill：${alias}`,
+        detail: `启用 ${availableSkill.source}/${availableSkill.collection}/${availableSkill.name} 到项目后，会与全局 ${alias} 同名。`,
+        alias,
+        skillId: availableSkill.id,
+        global: globalMatches.map(formatSkillLocation)
+      });
+    }
+  }
+
+  for (const skill of hermes) {
+    const matchingSource = skills.find((candidate) => candidate.path === skill.targetPath);
+    const managedTarget = skill.isSymlink && isInsideAllowedSkillSources(roots, skill.targetPath);
+    if (!matchingSource && !managedTarget) continue;
+
+    if (!skill.isSymlink) {
+      advice.push({
+        severity: 'warning',
+        type: 'hermes-unmanaged-entry',
+        title: `Hermes 存在非软链接 skill：${skill.alias}`,
+        detail: `${skill.linkPath} 不是 Skillcaddy 可安全清理的软链接。启用同名 Hermes skill 前请先确认该条目用途。`,
+        alias: skill.alias,
+        path: skill.linkPath,
+        scope: 'hermes'
+      });
+      continue;
+    }
+
+    if (!skill.exists) {
+      advice.push({
+        severity: 'warning',
+        type: 'hermes-broken-link',
+        title: `Hermes skill 断链：${skill.alias}`,
+        detail: `${skill.linkPath} 指向不存在的目标：${skill.targetPath}`,
+        alias: skill.alias,
+        path: skill.linkPath,
+        targetPath: skill.targetPath,
+        scope: 'hermes'
+      });
+      continue;
+    }
+
+    if (!isInsideAllowedSkillSources(roots, skill.targetPath)) {
+      advice.push({
+        severity: 'info',
+        type: 'hermes-unmanaged-symlink',
+        title: `Hermes 存在不纳管 skill：${skill.alias}`,
+        detail: `${skill.alias} 指向当前 Skillcaddy 来源目录之外：${skill.targetPath}`,
+        alias: skill.alias,
+        path: skill.linkPath,
+        targetPath: skill.targetPath,
+        scope: 'hermes'
+      });
+    }
+  }
+
+  for (const [name, matches] of availableByName) {
+    if (matches.length <= 1) continue;
+    const reservedAliases = new Set([
+      ...projectByAlias.keys(),
+      ...globalByAlias.keys(),
+      ...hermesByAlias.keys()
+    ]);
+    const skillsWithAliases = matches.map((skill) => ({
+      id: skill.id,
+      source: skill.source,
+      collection: skill.collection,
+      path: skill.path,
+      suggestedAlias: suggestUniqueAlias(skill, reservedAliases)
+    }));
+    advice.push({
+      severity: 'info',
+      type: 'library-duplicate-name',
+      title: `原件库存在同名 skill：${name}`,
+      detail: `启用时需要按来源确认；可在 skill 详情中使用建议名称，避免默认 alias ${name} 指向非预期 skill。`,
+      alias: name,
+      skills: skillsWithAliases,
+      actions: skillsWithAliases.map((skill) => ({
+        type: 'enable-with-alias',
+        skillId: skill.id,
+        alias: skill.suggestedAlias
+      }))
+    });
+  }
+
+  return advice.sort((left, right) => severityRank(right.severity) - severityRank(left.severity) || left.title.localeCompare(right.title));
+}
+
+function suggestUniqueAlias(skill, reservedAliases) {
+  const prefix = skill.collection === skill.name ? skill.source : skill.collection;
+  const base = normalizeSuggestedAlias(`${prefix}-${skill.name}`) || normalizeSuggestedAlias(`${skill.source}-${skill.name}`) || 'skill';
+  let alias = base;
+  let suffix = 2;
+  while (reservedAliases.has(alias)) {
+    alias = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  reservedAliases.add(alias);
+  return alias;
+}
+
+function normalizeSuggestedAlias(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function groupBy(items, getKey) {
+  const groups = new Map();
+  for (const item of items) {
+    const key = getKey(item);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(item);
+  }
+  return groups;
+}
+
+function formatSkillLocation(skill) {
+  return {
+    alias: skill.alias,
+    path: skill.linkPath,
+    targetPath: skill.targetPath,
+    isSymlink: skill.isSymlink,
+    exists: skill.exists,
+    agent: skill.agent
+  };
+}
+
+function severityRank(severity) {
+  return { warning: 2, info: 1 }[severity] || 0;
+}
+
+export async function enableSkill(roots, input) {
+  const resolvedRoots = normalizeRoots(roots);
+  const scope = normalizeEnablementScope(input.scope);
+  const skillPath = requirePath(input.skillPath, 'skillPath');
+  const alias = normalizeAlias(input.alias || path.basename(skillPath));
+  const resolvedSkillPath = path.resolve(skillPath);
+
+  assertInsideSources(resolvedRoots, resolvedSkillPath);
+  await assertDirectory(resolvedSkillPath, 'skillPath');
+  assertHermesEligible(resolvedRoots, resolvedSkillPath, scope);
+
+  const skillsDir = getScopeSkillsDir(scope, input);
+  await mkdir(skillsDir, { recursive: true });
+
+  const linkPath = path.join(skillsDir, alias);
+  if (await linkPathExists(linkPath)) {
+    const stat = await lstat(linkPath);
+    if (!stat.isSymbolicLink()) {
+      throw new Error(`目标已存在且不是软链接：${linkPath}`);
+    }
+
+    const existingTarget = await resolveLinkTarget(linkPath);
+    if (existingTarget !== resolvedSkillPath) {
+      throw new Error(`别名已指向其他 skill：${existingTarget}`);
+    }
+
+    return { ok: true, scope, alias, linkPath, targetPath: resolvedSkillPath, unchanged: true };
+  }
+
+  await symlink(resolvedSkillPath, linkPath, 'dir');
+  return { ok: true, scope, alias, linkPath, targetPath: resolvedSkillPath, unchanged: false };
+}
+
+export async function disableSkill(input) {
+  const scope = normalizeEnablementScope(input.scope);
+  const alias = normalizeAlias(input.alias);
+  const linkPath = path.join(getScopeSkillsDir(scope, input), alias);
+
+  if (!(await linkPathExists(linkPath))) {
+    return { ok: true, scope, alias, linkPath, removed: false };
+  }
+
+  const stat = await lstat(linkPath);
+  if (!stat.isSymbolicLink()) {
+    throw new Error(`拒绝删除非软链接：${linkPath}`);
+  }
+
+  if (scope === 'global' || scope === 'hermes') {
+    const roots = resolveDisableRoots(input);
+    if (!roots) {
+      throw new Error(`${scope} disable requires rootDir`);
+    }
+    const targetPath = await resolveLinkTarget(linkPath);
+    if (!isInsideAllowedSkillSources(roots, targetPath)) {
+      throw new Error(`拒绝清理不属于当前 Skillcaddy 原件库的 ${scope} 软链接：${targetPath}`);
+    }
+  }
+
+  await rm(linkPath);
+  return { ok: true, scope, alias, linkPath, removed: true };
+}
+
+export function getGlobalSkillsDir(globalDir) {
+  return path.resolve(globalDir || path.join(homedir(), '.agents', 'skills'));
+}
+
+function getScopeSkillsDir(scope, input) {
+  if (scope === 'global') return getGlobalSkillsDir(input.globalDir);
+  if (scope === 'hermes') return getHermesSkillsDir(input.hermesDir);
+  return getAgentsSkillsDir(normalizeProjectPath(input.projectPath));
+}
+
+function assertHermesEligible(roots, skillPath, scope) {
+  if (scope !== 'hermes') return;
+  const source = resolveAllowedSkillSource(roots, skillPath);
+  if (!source || !isHermesEligibleSource(source.sourceFolder)) {
+    throw new Error('Hermes 只允许启用 official、github 或 personal 来源的 skill');
+  }
+}
+
+function getAgentsSkillsDir(projectPath) {
+  return path.join(normalizeProjectPath(projectPath), '.agents', 'skills');
+}
+
+async function scanSourceEntry(roots, source, sourceDir, entryName) {
+  const entryPath = path.join(sourceDir, entryName);
+  if (await sourcePublicationInProgress(entryPath)) return [];
+  const skillDirs = await discoverSourceSkillDirectories(entryPath);
+  if (await sourcePublicationInProgress(entryPath)) return [];
+  return Promise.all(
+    skillDirs.map((skillPath) => {
+      const relative = path.relative(sourceDir, skillPath);
+      const name = relative === `${entryName}/skills` ? entryName : path.basename(skillPath);
+      return buildSkillRecord(roots, source, sourceDir, skillPath, name, entryName);
+    })
+  );
+}
+
+async function sourcePublicationInProgress(sourcePath) {
+  try {
+    return await readFile(
+      path.join(sourcePath, SOURCE_INSTALLING_MARKER),
+      'utf8'
+    ) === SOURCE_INSTALLING_MARKER_CONTENT;
+  } catch {
+    return false;
+  }
+}
+
+async function buildSkillRecord(roots, source, sourceDir, skillPath, name, collection) {
+  const skillFile = path.join(skillPath, 'SKILL.md');
+  const relativePath = path.relative(sourceDir, skillPath);
+  const [description, metadata] = await Promise.all([
+    readSkillDescription(skillFile),
+    readSkillMetadata(roots, skillPath)
+  ]);
+  const collectionPath = path.join(sourceDir, collection);
+
+  return {
+    id: `${source}/${relativePath}`,
+    source,
+    collection,
+    collectionPath,
+    name,
+    path: skillPath,
+    relativePath,
+    hasSkillFile: true,
+    description,
+    note: metadata.note,
+    tags: metadata.tags,
+    autoEnable: metadata.autoEnable,
+    metadataPath: metadata.metadataPath,
+    metadataStorage: metadata.metadataStorage,
+    hasMetadata: metadata.hasMetadata,
+    metadataError: metadata.metadataError
+  };
+}
+
+async function readSkillDescription(skillFile) {
+  const content = await readFile(skillFile, 'utf8');
+  const match = content.match(/^description:\s*(.+)$/m);
+  return match ? match[1].replace(/^["']|["']$/g, '') : firstMarkdownLine(content);
+}
+
+function firstMarkdownLine(content) {
+  return content
+    .split('\n')
+    .map((line) => line.trim())
+    .find((line) => line && !line.startsWith('---') && !line.startsWith('#')) || '';
+}
+
+async function safeReaddir(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+async function assertDirectory(targetPath, label) {
+  const stat = await lstat(targetPath);
+  if (!stat.isDirectory()) {
+    throw new Error(`${label} 必须是目录：${targetPath}`);
+  }
+}
+
+function assertInsideSources(roots, skillPath) {
+  assertInsideAllowedSkillSources(roots, skillPath);
+}
+
+/**
+ * disable 的 roots 解析。优先接受完整的 roots 对象；历史调用点只传 rootDir
+ * （原件库根），此时代码根退化为同一个目录。
+ */
+function resolveDisableRoots(input) {
+  if (input.roots && typeof input.roots === 'object') {
+    return normalizeRoots(input.roots);
+  }
+  if (typeof input.rootDir === 'string' && input.rootDir) {
+    return normalizeRoots(input.rootDir, { codeRoot: input.codeRoot });
+  }
+  if (typeof input.libraryRoot === 'string' && input.libraryRoot) {
+    return normalizeRoots(input.libraryRoot, { codeRoot: input.codeRoot });
+  }
+  return null;
+}
+
+function normalizeAlias(value) {
+  if (!value || typeof value !== 'string') {
+    throw new Error('alias 不能为空');
+  }
+
+  const alias = value.trim();
+  if (!/^[a-zA-Z0-9._-]+$/.test(alias)) {
+    throw new Error('alias 只能包含字母、数字、点、下划线和短横线');
+  }
+
+  return alias;
+}
+
+function buildSourcesInfo(records) {
+  return records.map((record) => {
+    const info = {
+      sourceId: record.sourceId,
+      type: record.type,
+      installPath: record.installPath
+    };
+
+    if (record.type === 'git' && record.origin?.commit) {
+      info.version = record.origin.commit.slice(0, 7);
+    } else if (record.integrity?.value) {
+      info.version = record.integrity.value.slice(0, 12);
+      info.algorithm = record.integrity.algorithm;
+    }
+
+    return info;
+  });
+}