skillcaddy 0.27.0

package/lib/collectionEnablement.js

@@ -0,0 +1,115 @@
+import { buildCollectionEnablePlan } from './enablePlan.js';
+import { enableProjectSkill } from './projectActions.js';
+import { getState } from './skillStore.js';
+import { normalizeEnablementScope } from './enablementScope.js';
+import { normalizeRoots } from './roots.js';
+
+export async function executeCollectionEnablement(roots, input) {
+  const resolvedRoots = normalizeRoots(roots);
+  const scope = normalizeEnablementScope(input.scope);
+  const projectPath = input.projectPath || resolvedRoots.libraryRoot;
+  const skillIds = normalizeSkillIds(input.skillIds);
+  const state = await getState(resolvedRoots, projectPath, {
+    globalDir: input.globalDir,
+    hermesDir: input.hermesDir
+  });
+  const plan = buildCollectionEnablePlan(state, skillIds, { scope });
+  const skillsById = new Map(state.skills.map((skill) => [skill.id, skill]));
+  const outcomes = [
+    ...plan.unchangedSkillIds.map((skillId) => buildStaticOutcome(skillsById, skillId, 'unchanged')),
+    ...plan.skippedSkillIds.map((skillId) => buildStaticOutcome(skillsById, skillId, 'skipped'))
+  ];
+
+  for (const skillId of plan.targetSkillIds) {
+    const skill = skillsById.get(skillId);
+    try {
+      const result = await enableProjectSkill(resolvedRoots, {
+        ...(scope === 'project' ? { projectPath: state.projectPath } : {}),
+        scope,
+        ...(input.globalDir ? { globalDir: input.globalDir } : {}),
+        ...(input.hermesDir ? { hermesDir: input.hermesDir } : {}),
+        skillPath: skill.path,
+        alias: skill.name
+      });
+      outcomes.push({
+        skillId,
+        alias: result.alias,
+        status: result.unchanged ? 'unchanged' : 'enabled',
+        claudeSync: result.claudeSync
+      });
+    } catch (error) {
+      outcomes.push({
+        skillId,
+        alias: skill.name,
+        status: 'failed',
+        error: error.message || 'Collection enablement failed'
+      });
+    }
+  }
+
+  const refreshed = scope !== 'project'
+    ? { setups: [], reminders: [], refresh: { ok: true } }
+    : await refreshSetupGuidance(resolvedRoots, state.projectPath, plan.setups, input.globalDir, input.hermesDir);
+  return {
+    scope,
+    plan,
+    outcomes,
+    counts: countOutcomes(outcomes),
+    setups: refreshed.setups,
+    reminders: refreshed.reminders,
+    refresh: refreshed.refresh
+  };
+}
+
+function normalizeSkillIds(value) {
+  if (!Array.isArray(value)) throw new Error('skillIds 必须是数组');
+  return [...new Set(value.map((skillId) => {
+    if (typeof skillId !== 'string' || !skillId.trim()) {
+      throw new Error('skillIds 只能包含非空字符串');
+    }
+    return skillId.trim();
+  }))];
+}
+
+function buildStaticOutcome(skillsById, skillId, status) {
+  const skill = skillsById.get(skillId);
+  return {
+    skillId,
+    alias: skill.name,
+    status
+  };
+}
+
+function countOutcomes(outcomes) {
+  const counts = {
+    enabled: 0,
+    unchanged: 0,
+    skipped: 0,
+    failed: 0
+  };
+  for (const outcome of outcomes) counts[outcome.status] += 1;
+  return counts;
+}
+
+async function refreshSetupGuidance(roots, projectPath, plannedSetups, globalDir, hermesDir) {
+  try {
+    const state = await getState(roots, projectPath, { globalDir, hermesDir });
+    const setupIds = new Set(plannedSetups.map((setup) => setup.id));
+    return {
+      setups: state.setups.filter((setup) => setupIds.has(setup.id)),
+      reminders: state.advice.filter((advice) =>
+        setupIds.has(advice.collection) && advice.type.startsWith('collection-setup-')
+      ),
+      refresh: { ok: true }
+    };
+  } catch (error) {
+    return {
+      setups: plannedSetups,
+      reminders: [],
+      refresh: {
+        ok: false,
+        error: error.message || 'Collection setup guidance refresh failed'
+      }
+    };
+  }
+}

package/lib/collectionSetup.js

@@ -0,0 +1,199 @@
+import { constants } from 'node:fs';
+import { access, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeRoots } from './roots.js';
+
+const CONTRACT_ROOT = 'collection-metadata';
+const SUPPORTED_SCHEMA_VERSION = 1;
+
+export async function scanCollectionSetups(roots, projectPath, skills, enabled) {
+  const { codeRoot } = normalizeRoots(roots);
+  const collections = uniqueCollections(skills);
+  const enabledTargets = new Set(enabled.map((skill) => skill.targetPath).filter(Boolean));
+  const results = await Promise.all(collections.map(async (collection) => {
+    const contractPath = path.join(codeRoot, CONTRACT_ROOT, collection.source, `${collection.collection}.json`);
+    try {
+      const contract = await readContract(contractPath);
+      if (!contract) return null;
+      return await evaluateSetupContract({
+        collection,
+        contract: normalizeContract(contract, collection, skills),
+        contractPath,
+        projectPath,
+        skills,
+        enabledTargets
+      });
+    } catch (error) {
+      return {
+        id: collection.id,
+        source: collection.source,
+        collection: collection.collection,
+        contractPath,
+        status: 'invalid',
+        error: error.message
+      };
+    }
+  }));
+
+  return results.filter(Boolean).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function buildCollectionSetupAdvice(setups) {
+  const advice = [];
+
+  for (const setup of setups) {
+    if (setup.status === 'invalid') {
+      advice.push({
+        severity: 'warning',
+        type: 'collection-setup-invalid',
+        title: `库初始化配置无效：${setup.id}`,
+        detail: setup.error,
+        collection: setup.id,
+        contractPath: setup.contractPath
+      });
+      continue;
+    }
+
+    if (setup.affectedEnabledSkillIds.length === 0 || setup.status === 'ready') continue;
+    const required = setup.requirement === 'required';
+    const statusText = setup.status === 'partial' ? '仅完成部分配置' : '尚未配置';
+    const setupSkillText = setup.setupSkillEnabled ? '' : ` 初始化 skill ${setup.setupSkillName} 尚未启用。`;
+    advice.push({
+      severity: required ? 'warning' : 'info',
+      type: required ? 'collection-setup-required' : 'collection-setup-recommended',
+      title: `${setup.id} 已启用但${statusText}`,
+      detail: `缺少：${setup.missingArtifacts.join('、')}。${setupSkillText}请在 Agent 中运行 ${setup.setupSkillName}。`,
+      collection: setup.id,
+      status: setup.status,
+      setupSkillId: setup.setupSkillId,
+      missingArtifacts: setup.missingArtifacts,
+      affectedSkillIds: setup.affectedEnabledSkillIds,
+      actions: [{
+        type: 'run-setup-skill',
+        skillId: setup.setupSkillId,
+        instruction: setup.instruction
+      }]
+    });
+  }
+
+  return advice;
+}
+
+async function evaluateSetupContract({ collection, contract, contractPath, projectPath, skills, enabledTargets }) {
+  const artifacts = await Promise.all(contract.requiredArtifacts.map(async (relativePath) => ({
+    path: relativePath,
+    exists: await pathExists(path.resolve(projectPath, relativePath))
+  })));
+  const existingCount = artifacts.filter((artifact) => artifact.exists).length;
+  const status = existingCount === 0 ? 'missing' : existingCount === artifacts.length ? 'ready' : 'partial';
+  const applicableSkills = skills.filter((skill) =>
+    skill.id !== contract.skillId && contract.appliesTo.some((pattern) => matchesPattern(skill.id, pattern))
+  );
+  const setupSkill = skills.find((skill) => skill.id === contract.skillId);
+
+  return {
+    id: collection.id,
+    source: collection.source,
+    collection: collection.collection,
+    contractPath,
+    requirement: contract.requirement,
+    scope: contract.scope,
+    mode: contract.mode,
+    status,
+    setupSkillId: setupSkill.id,
+    setupSkillName: setupSkill.name,
+    setupSkillEnabled: enabledTargets.has(setupSkill.path),
+    applicableSkillIds: applicableSkills.map((skill) => skill.id),
+    affectedEnabledSkillIds: applicableSkills.filter((skill) => enabledTargets.has(skill.path)).map((skill) => skill.id),
+    requiredArtifacts: artifacts.map((artifact) => artifact.path),
+    missingArtifacts: artifacts.filter((artifact) => !artifact.exists).map((artifact) => artifact.path),
+    instruction: `请运行 ${setupSkill.name}，完成 ${collection.id} 的项目初始化。`
+  };
+}
+
+function normalizeContract(value, collection, skills) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('setup contract 必须是对象');
+  if (value.schemaVersion !== SUPPORTED_SCHEMA_VERSION) throw new Error(`schemaVersion 必须是 ${SUPPORTED_SCHEMA_VERSION}`);
+  const setup = value.setup;
+  if (!setup || typeof setup !== 'object' || Array.isArray(setup)) throw new Error('setup 字段必须是对象');
+  if (!['required', 'recommended'].includes(setup.requirement)) throw new Error('setup.requirement 必须是 required 或 recommended');
+  if (setup.scope !== 'project') throw new Error('setup.scope 当前只支持 project');
+  if (setup.mode !== 'interactive') throw new Error('setup.mode 当前只支持 interactive');
+  if (typeof setup.skillId !== 'string' || !setup.skillId.trim()) throw new Error('setup.skillId 不能为空');
+
+  const setupSkill = skills.find((skill) => skill.id === setup.skillId);
+  if (!setupSkill || setupSkill.source !== collection.source || setupSkill.collection !== collection.collection) {
+    throw new Error('setup.skillId 必须指向当前库中存在的 skill');
+  }
+
+  const appliesTo = normalizePatterns(setup.appliesTo);
+  const requiredArtifacts = normalizeArtifacts(setup.requiredArtifacts);
+  if (!skills.some((skill) => skill.id !== setup.skillId && appliesTo.some((pattern) => matchesPattern(skill.id, pattern)))) {
+    throw new Error('setup.appliesTo 没有匹配当前库中的 skill');
+  }
+
+  return {
+    requirement: setup.requirement,
+    scope: setup.scope,
+    mode: setup.mode,
+    skillId: setup.skillId,
+    appliesTo,
+    requiredArtifacts
+  };
+}
+
+function normalizePatterns(value) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('setup.appliesTo 必须是非空数组');
+  return value.map((pattern) => {
+    if (typeof pattern !== 'string' || !pattern.trim()) throw new Error('setup.appliesTo 只能包含字符串');
+    const text = pattern.trim();
+    const star = text.indexOf('*');
+    if (star !== -1 && (star !== text.length - 1 || text.indexOf('*', star + 1) !== -1)) {
+      throw new Error('setup.appliesTo 仅支持末尾 * 通配符');
+    }
+    return text;
+  });
+}
+
+function normalizeArtifacts(value) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('setup.requiredArtifacts 必须是非空数组');
+  return [...new Set(value.map((artifact) => {
+    if (typeof artifact !== 'string' || !artifact.trim()) throw new Error('setup.requiredArtifacts 只能包含字符串');
+    const normalized = path.normalize(artifact.trim());
+    if (path.isAbsolute(normalized) || normalized === '.' || normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
+      throw new Error('setup.requiredArtifacts 必须是项目内相对路径');
+    }
+    return normalized;
+  }))];
+}
+
+function uniqueCollections(skills) {
+  const collections = new Map();
+  for (const skill of skills) {
+    const id = `${skill.source}/${skill.collection}`;
+    if (!collections.has(id)) collections.set(id, { id, source: skill.source, collection: skill.collection });
+  }
+  return [...collections.values()];
+}
+
+function matchesPattern(value, pattern) {
+  return pattern.endsWith('*') ? value.startsWith(pattern.slice(0, -1)) : value === pattern;
+}
+
+async function readContract(contractPath) {
+  try {
+    return JSON.parse(await readFile(contractPath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/enablePlan.js

@@ -0,0 +1,116 @@
+import { normalizeEnablementScope } from './enablementScope.js';
+import { isHermesEligibleSource } from './hermesStore.js';
+
+export function buildCollectionEnablePlan(state, skillIds, options = {}) {
+  const scope = normalizeEnablementScope(
+    typeof options === 'string' ? options : options.scope
+  );
+  const requestedIds = new Set(skillIds);
+  const requestedSkills = state.skills.filter((skill) => requestedIds.has(skill.id));
+  if (requestedSkills.length !== requestedIds.size) {
+    const knownIds = new Set(requestedSkills.map((skill) => skill.id));
+    const missing = [...requestedIds].filter((skillId) => !knownIds.has(skillId));
+    throw new Error(`找不到待启用 skill：${missing.join(', ')}`);
+  }
+
+  const enabledTargets = new Set(
+    enabledSkillsForScope(state, scope)
+      .map((skill) => skill.targetPath)
+      .filter(Boolean)
+  );
+  const setups = scope === 'project'
+    ? findSetupsForSkillIds(state, skillIds).filter((setup) => setup.status !== 'ready')
+    : [];
+  const setupSkillIds = new Set(setups.filter((setup) => !setup.setupSkillEnabled).map((setup) => setup.setupSkillId));
+  const expandedSkills = [];
+
+  for (const setupSkillId of setupSkillIds) {
+    const setupSkill = state.skills.find((skill) => skill.id === setupSkillId);
+    if (setupSkill) expandedSkills.push(setupSkill);
+  }
+  for (const skill of requestedSkills) {
+    if (!setupSkillIds.has(skill.id)) expandedSkills.push(skill);
+  }
+
+  const targetSkillIds = [];
+  const skippedSkillIds = [];
+  const unchangedSkillIds = [];
+
+  for (const skill of expandedSkills) {
+    if (enabledTargets.has(skill.path)) {
+      unchangedSkillIds.push(skill.id);
+    } else if (scope === 'hermes' && !isHermesEligibleSource(skill.source)) {
+      skippedSkillIds.push(skill.id);
+    } else if (skill.source === 'archived' || (skill.autoEnable === false && !setupSkillIds.has(skill.id))) {
+      skippedSkillIds.push(skill.id);
+    } else {
+      targetSkillIds.push(skill.id);
+    }
+  }
+
+  return { scope, targetSkillIds, skippedSkillIds, unchangedSkillIds, setups };
+}
+
+export function buildSkillEnablePlan(state, skillId, requestedAlias, scope = 'project') {
+  scope = normalizeEnablementScope(scope);
+  const matches = state.skills.filter((skill) => skill.id === skillId);
+  if (matches.length !== 1) {
+    throw new Error(`Expected one acquired skill for ${skillId}; found ${matches.length}`);
+  }
+
+  const skill = matches[0];
+  if (scope === 'hermes' && !isHermesEligibleSource(skill.source)) {
+    throw new Error(`Hermes 不允许启用 ${skill.source} 来源的 skill：${skill.id}`);
+  }
+  const alias = requestedAlias || skill.name;
+  const existing = enabledSkillsForScope(state, scope)
+    .find((enabledSkill) => enabledSkill.alias === alias);
+  if (
+    existing &&
+    (!existing.isSymlink || existing.targetPath !== skill.path)
+  ) {
+    throw new Error(`${scopeLabel(scope)} alias is occupied by another entry: ${alias}`);
+  }
+
+  return {
+    skillId: skill.id,
+    skillPath: skill.path,
+    alias,
+    scope,
+    status: existing ? 'unchanged' : 'ready',
+    reminders: scope === 'project' ? findSetupReminders(state, skill.id) : []
+  };
+}
+
+function enabledSkillsForScope(state, scope) {
+  if (scope === 'global') return state.global || [];
+  if (scope === 'hermes') return state.hermes || [];
+  return state.enabled || [];
+}
+
+function scopeLabel(scope) {
+  return { global: 'Global', hermes: 'Hermes', project: 'Project' }[scope] || scope;
+}
+
+function findSetupsForSkillIds(state, skillIds) {
+  const candidates = new Set(skillIds);
+  return (state.setups || []).filter((setup) =>
+    setup.status !== 'invalid' && setup.applicableSkillIds.some((skillId) => candidates.has(skillId))
+  );
+}
+
+function findSetupReminders(state, skillId) {
+  const setupIds = new Set(
+    findSetupsForSkillIds(state, [skillId])
+      .filter((setup) => setup.status !== 'ready')
+      .map((setup) => setup.setupSkillId)
+  );
+  return (state.advice || []).filter(
+    (advice) =>
+      (
+        advice.type === 'collection-setup-required' ||
+        advice.type === 'collection-setup-recommended'
+      ) &&
+      setupIds.has(advice.setupSkillId)
+  );
+}

package/lib/enablementScope.js

@@ -0,0 +1,8 @@
+export const ENABLEMENT_SCOPES = Object.freeze(['project', 'global', 'hermes']);
+
+export function normalizeEnablementScope(value = 'project') {
+  if (!ENABLEMENT_SCOPES.includes(value)) {
+    throw new Error(`scope 必须是 project、global 或 hermes：${value}`);
+  }
+  return value;
+}

package/lib/hermesStore.js

@@ -0,0 +1,21 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { scanSkillLinks } from './skillLinkStore.js';
+
+export const HERMES_ELIGIBLE_SOURCES = Object.freeze(['official', 'github', 'personal']);
+
+export function getHermesSkillsDir(hermesDir) {
+  return path.resolve(hermesDir || path.join(homedir(), '.hermes', 'skills'));
+}
+
+export async function scanHermesSkills({ hermesDir } = {}) {
+  const directory = getHermesSkillsDir(hermesDir);
+  const skills = await scanSkillLinks(directory);
+  return skills
+    .map((skill) => ({ ...skill, agent: 'Hermes', scope: 'hermes', directory }))
+    .sort((left, right) => left.alias.localeCompare(right.alias));
+}
+
+export function isHermesEligibleSource(source) {
+  return HERMES_ELIGIBLE_SOURCES.includes(source);
+}