skillcaddy 0.27.0

package/lib/managerInstall.js

@@ -0,0 +1,109 @@
+import { access, lstat, mkdir, readlink, symlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { normalizeRoots } from './roots.js';
+
+const MANAGER_SKILL_NAME = 'skillcaddy-manager';
+
+export function getManagerInstallPaths(roots, options = {}) {
+  const homeDir = options.homeDir || homedir();
+  const { codeRoot } = normalizeRoots(roots);
+  return {
+    sourcePath: path.join(codeRoot, 'skills', MANAGER_SKILL_NAME),
+    targetPath: path.join(path.resolve(homeDir), '.agents', 'skills', MANAGER_SKILL_NAME)
+  };
+}
+
+export async function checkManagerInstall(rootDir, options = {}) {
+  const paths = getManagerInstallPaths(rootDir, options);
+  const sourceOk = await isSkillDirectory(paths.sourcePath);
+  if (!sourceOk) {
+    return {
+      ok: false,
+      status: 'source-missing',
+      ...paths,
+      message: `manager skill source is missing: ${paths.sourcePath}`
+    };
+  }
+
+  const target = await safeLstat(paths.targetPath);
+  if (!target) {
+    return {
+      ok: false,
+      status: 'missing',
+      ...paths,
+      message: `manager skill is not installed: ${paths.targetPath}`
+    };
+  }
+
+  if (!target.isSymbolicLink()) {
+    return {
+      ok: false,
+      status: 'conflict',
+      ...paths,
+      message: `target exists but is not a symlink: ${paths.targetPath}`
+    };
+  }
+
+  const linkTarget = await readlink(paths.targetPath);
+  const resolvedTarget = path.resolve(path.dirname(paths.targetPath), linkTarget);
+  if (resolvedTarget !== paths.sourcePath) {
+    return {
+      ok: false,
+      status: 'conflict',
+      ...paths,
+      linkTarget: resolvedTarget,
+      message: `target symlink points elsewhere: ${resolvedTarget}`
+    };
+  }
+
+  return {
+    ok: true,
+    status: 'installed',
+    ...paths,
+    linkTarget: resolvedTarget,
+    message: `manager skill is installed: ${paths.targetPath}`
+  };
+}
+
+export async function installManagerSkill(rootDir, options = {}) {
+  const current = await checkManagerInstall(rootDir, options);
+  if (current.status === 'installed') {
+    return { ...current, unchanged: true };
+  }
+
+  if (current.status !== 'missing') {
+    throw new Error(current.message);
+  }
+
+  await mkdir(path.dirname(current.targetPath), { recursive: true });
+  await symlink(current.sourcePath, current.targetPath, 'dir');
+
+  const installed = await checkManagerInstall(rootDir, options);
+  if (!installed.ok) {
+    throw new Error(installed.message);
+  }
+
+  return { ...installed, unchanged: false };
+}
+
+async function isSkillDirectory(skillPath) {
+  const stat = await safeLstat(skillPath);
+  if (!stat?.isDirectory()) return false;
+
+  try {
+    await access(path.join(skillPath, 'SKILL.md'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeLstat(targetPath) {
+  try {
+    return await lstat(targetPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}

package/lib/managerSourceWorkflow.js

@@ -0,0 +1,234 @@
+import path from 'node:path';
+import { buildSkillEnablePlan } from './enablePlan.js';
+import { enableProjectSkill } from './projectActions.js';
+import {
+  applyAddSource,
+  applyUpdateSource,
+  listSources,
+  planAddSource,
+  planBreakingUpdateSource,
+  planUpdateSource
+} from './sourceManager.js';
+import { getState } from './skillStore.js';
+import { normalizeEnablementScope } from './enablementScope.js';
+import { normalizeRoots } from './roots.js';
+
+const workflowPlans = new WeakMap();
+
+export async function planManagerSourceWorkflow(context, request) {
+  const acquisitionRequest = request?.acquisition || null;
+  const enablementRequest = request?.enablement || null;
+  if (!acquisitionRequest && !enablementRequest) {
+    throw new Error('Manager workflow requires acquisition or enablement intent');
+  }
+
+  const acquisition = acquisitionRequest
+    ? await planAcquisition(context, acquisitionRequest)
+    : null;
+  const enablement = enablementRequest
+    ? await planEnablement(context, acquisition, enablementRequest)
+    : null;
+  const plan = {
+    operation: 'manager-source-workflow',
+    acquisition: acquisition && {
+      action: acquisition.action,
+      plan: acquisition.plan
+    },
+    enablement
+  };
+
+  workflowPlans.set(plan, {
+    acquisition,
+    enablementRequest
+  });
+  return plan;
+}
+
+export async function applyManagerSourceWorkflow(context, plan) {
+  const privatePlan = workflowPlans.get(plan);
+  if (!privatePlan) {
+    throw new Error('The Manager workflow plan must be applied by the process that created it');
+  }
+
+  const acquisition = await applyAcquisition(context, privatePlan.acquisition);
+  const enablement = privatePlan.enablementRequest
+    ? await applyEnablement(
+        context,
+        plan.acquisition?.plan || null,
+        privatePlan.enablementRequest
+      )
+    : null;
+
+  return { acquisition, enablement };
+}
+
+async function planAcquisition(context, request) {
+  const registeredSource = request.sourceId
+    ? await findRegisteredSource(context, request.sourceId)
+    : null;
+
+  if (request.sourceId && !registeredSource) {
+    throw new Error(`Source is not registered: ${request.sourceId}`);
+  }
+
+  if (registeredSource) {
+    return planRegisteredUpdate(context, request, registeredSource.sourceId);
+  }
+
+  const addRequest = {
+      input: request.input,
+      ...(request.name === undefined ? {} : { name: request.name }),
+      ...(request.namespace === undefined ? {} : { namespace: request.namespace })
+  };
+  try {
+    return {
+      action: 'add',
+      plan: await planAddSource(context, addRequest)
+    };
+  } catch (error) {
+    if (!error.registeredSourceId) throw error;
+    return planRegisteredUpdate(context, request, error.registeredSourceId);
+  }
+}
+
+async function planRegisteredUpdate(context, request, sourceId) {
+  const planUpdate = request.allowBreaking
+    ? planBreakingUpdateSource
+    : planUpdateSource;
+  return {
+    action: 'update',
+    plan: await planUpdate(context, {
+      sourceId,
+      ...(request.input === undefined ? {} : { input: request.input })
+    })
+  };
+}
+
+async function findRegisteredSource(context, sourceId) {
+  const inventory = await listSources(context);
+  return inventory.sources.find(
+    (source) => source.status === 'registered' && source.sourceId === sourceId
+  );
+}
+
+/**
+ * Manager workflow 的两个根。
+ *
+ * `context.rootDir` 是原件库根（source 获取只写这里）；`context.roots` 可选，
+ * 用来把代码根一并带进来 —— 仓库自带 skills 与合集初始化契约都在代码根侧。
+ */
+function resolveWorkflowRoots(context) {
+  if (context.roots && typeof context.roots === 'object') return normalizeRoots(context.roots);
+  return normalizeRoots(context.rootDir);
+}
+
+async function planEnablement(context, acquisition, request) {
+  const roots = resolveWorkflowRoots(context);
+  const scope = normalizeEnablementScope(request.scope);
+  if (acquisition) {
+    const skillId = resolveAcquiredSkillId(acquisition.plan, request);
+    return {
+      skillId,
+      alias: request.alias || path.posix.basename(skillId),
+      scope,
+      status: 'pending-acquisition',
+      reminders: []
+    };
+  }
+
+  if (typeof request.skillId !== 'string' || !request.skillId.trim()) {
+    throw new Error('Enablement-only Manager requests require enablement.skillId');
+  }
+  const state = await getState(
+    roots,
+    scope === 'project' ? requireProjectPath(context) : context.projectPath || roots.libraryRoot,
+    { globalDir: context.globalDir, hermesDir: context.hermesDir }
+  );
+  return buildSkillEnablePlan(state, request.skillId, request.alias, scope);
+}
+
+async function applyAcquisition(context, acquisition) {
+  if (!acquisition) return null;
+  if (acquisition.action === 'add') {
+    return applyAddSource(context, acquisition.plan);
+  }
+  return applyUpdateSource(context, acquisition.plan);
+}
+
+async function applyEnablement(context, acquisitionPlan, request) {
+  const roots = resolveWorkflowRoots(context);
+  const scope = normalizeEnablementScope(request.scope);
+  const state = await getState(
+    roots,
+    scope === 'project' ? requireProjectPath(context) : context.projectPath || roots.libraryRoot,
+    { globalDir: context.globalDir, hermesDir: context.hermesDir }
+  );
+  const skillId = acquisitionPlan
+    ? resolveAcquiredSkillId(acquisitionPlan, request)
+    : request.skillId;
+  const enablementPlan = buildSkillEnablePlan(state, skillId, request.alias, scope);
+  const result = await enableProjectSkill(roots, {
+    ...(scope === 'project' ? { projectPath: context.projectPath } : {}),
+    scope,
+    ...(context.globalDir ? { globalDir: context.globalDir } : {}),
+    ...(context.hermesDir ? { hermesDir: context.hermesDir } : {}),
+    skillPath: enablementPlan.skillPath,
+    alias: enablementPlan.alias
+  });
+  const verifiedState = await getState(
+    roots,
+    scope === 'project' ? context.projectPath : context.projectPath || roots.libraryRoot,
+    { globalDir: context.globalDir, hermesDir: context.hermesDir }
+  );
+  const verifiedPlan = buildSkillEnablePlan(
+    verifiedState,
+    skillId,
+    enablementPlan.alias,
+    scope
+  );
+
+  return {
+    ...result,
+    skillId,
+    reminders: verifiedPlan.reminders
+  };
+}
+
+function resolveAcquiredSkillId(acquisitionPlan, request) {
+  const availableIds = new Map(
+    acquisitionPlan.skills.map((sourceSkillPath) => [
+      path.posix.join(acquisitionPlan.installPath, sourceSkillPath),
+      sourceSkillPath
+    ])
+  );
+
+  if (request.skillId) {
+    if (!availableIds.has(request.skillId)) {
+      throw new Error(
+        `Selected skill is not part of the acquired source: ${request.skillId}`
+      );
+    }
+    return request.skillId;
+  }
+
+  if (
+    typeof request.sourceSkillPath !== 'string' ||
+    !acquisitionPlan.skills.includes(request.sourceSkillPath)
+  ) {
+    throw new Error(
+      `Select one acquired skill: ${[...availableIds.keys()].join(', ')}`
+    );
+  }
+  return path.posix.join(acquisitionPlan.installPath, request.sourceSkillPath);
+}
+
+function requireProjectPath(context) {
+  if (
+    !context ||
+    typeof context.projectPath !== 'string' ||
+    !context.projectPath.trim()
+  ) {
+    throw new Error('Manager enablement requires context.projectPath');
+  }
+  return context.projectPath;
+}

package/lib/projectActions.js

@@ -0,0 +1,24 @@
+import { syncClaudeSkills } from './claudeStore.js';
+import { enableSkill } from './skillStore.js';
+
+export async function enableProjectSkill(roots, input) {
+  const result = await enableSkill(roots, input);
+
+  if (result.scope !== 'project') return result;
+
+  return {
+    ...result,
+    claudeSync: await syncClaudeBestEffort(input.projectPath)
+  };
+}
+
+async function syncClaudeBestEffort(projectPath) {
+  try {
+    return await syncClaudeSkills(projectPath);
+  } catch (error) {
+    return {
+      ok: false,
+      error: error.message || 'Claude Code 同步失败'
+    };
+  }
+}

package/lib/projectPath.js

@@ -0,0 +1,51 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const SYSTEM_PROJECT_PATHS = new Set([
+  path.parse(process.cwd()).root,
+  '/Applications',
+  '/Library',
+  '/System',
+  '/bin',
+  '/etc',
+  '/opt',
+  '/private',
+  '/sbin',
+  '/tmp',
+  '/usr',
+  '/var'
+]);
+
+export function normalizeProjectPath(value) {
+  const projectPath = requirePath(value, 'projectPath');
+  assertSafeProjectPath(projectPath);
+  return projectPath;
+}
+
+export function requirePath(value, label) {
+  if (!value || typeof value !== 'string') {
+    throw new Error(`${label} 不能为空`);
+  }
+
+  return path.resolve(value);
+}
+
+function assertSafeProjectPath(projectPath) {
+  if (SYSTEM_PROJECT_PATHS.has(projectPath)) {
+    throw new Error(`projectPath 不能是系统目录：${projectPath}`);
+  }
+
+  const homePath = path.resolve(homedir());
+  if (projectPath === homePath) {
+    throw new Error(`projectPath 不能是用户主目录：${projectPath}`);
+  }
+
+  if (isAncestor(projectPath, homePath)) {
+    throw new Error(`projectPath 不能是用户主目录的父目录：${projectPath}`);
+  }
+}
+
+function isAncestor(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+}

package/lib/roots.js

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+/**
+ * Skillcaddy 的两个根目录。
+ *
+ * - code root（代码根）：运行中的代码所在目录。clone 出来的仓库、npm 包目录、
+ *   Homebrew Cellar 目录都属于这一类。它提供 package.json、server.js、
+ *   scripts/、skills/、collection-metadata/ 这些"随发行形态一起走"的内容。
+ * - library root（原件库根）：原件库所在目录。它承载 official/github/personal/
+ *   archived 四个 source bucket，以及 .skillcaddy/sources 与 .skillcaddy/metadata。
+ *
+ * 两者解耦之前，原件库只能跟着代码走：`npx skillcaddy` 之类的临时安装形态会把
+ * 1GB 级原件库落在 npm 缓存目录里，缓存一清就没了。解耦之后原件库有一个稳定的、
+ * 与安装形态无关的位置。
+ */
+
+/** 覆盖原件库根的环境变量。历史脚本（pull-github.sh 等）已经在用这个名字。 */
+export const LIBRARY_ROOT_ENV = 'SKILLCADDY_ROOT';
+
+/**
+ * 默认原件库根：`~/.skillcaddy/library`。
+ *
+ * 刻意不直接用 `~/.skillcaddy`：原件库内部结构固定为
+ * `<libraryRoot>/{official,github,personal,archived}` 与
+ * `<libraryRoot>/.skillcaddy/{sources,metadata}`，与 library image 的成员定义
+ * （ADR-0011）保持一致，这样导出的镜像可以被另一台机器原样导入。
+ */
+export function getDefaultLibraryRoot(homeDir = homedir()) {
+  return path.join(homeDir, '.skillcaddy', 'library');
+}
+
+/**
+ * 是否是 git checkout。clone 出来的仓库与 git worktree 都会带 `.git`
+ * （worktree 是文件，clone 是目录），npm 包目录与发行 tarball 都不会带。
+ */
+export function isCheckoutRoot(codeRoot) {
+  if (!codeRoot) return false;
+  return existsSync(path.join(codeRoot, '.git'));
+}
+
+/**
+ * 解析原件库根。优先级：
+ *
+ * 1. 显式传入的 libraryRoot（CLI 参数、调用方决策）；
+ * 2. `SKILLCADDY_ROOT` 环境变量；
+ * 3. 代码根是 git checkout —— 原件库继续留在 checkout 里，保持既有行为不变；
+ * 4. `~/.skillcaddy/library`。
+ *
+ * 第 3 条是兼容既有 clone 用户的关键：他们已经装好的原件库不会因为这次重构
+ * 而"凭空消失"。
+ */
+export function resolveLibraryRoot({ codeRoot, libraryRoot, env = process.env } = {}) {
+  if (libraryRoot) return path.resolve(libraryRoot);
+
+  const fromEnv = env?.[LIBRARY_ROOT_ENV];
+  if (fromEnv) return path.resolve(fromEnv);
+
+  if (codeRoot && isCheckoutRoot(codeRoot)) return path.resolve(codeRoot);
+
+  return getDefaultLibraryRoot();
+}
+
+/**
+ * 同时解析两个根。`codeRoot` 缺省为当前工作目录。
+ */
+export function resolveRoots({ codeRoot, libraryRoot, env = process.env } = {}) {
+  const resolvedCodeRoot = path.resolve(codeRoot || process.cwd());
+  return {
+    codeRoot: resolvedCodeRoot,
+    libraryRoot: resolveLibraryRoot({ codeRoot: resolvedCodeRoot, libraryRoot, env })
+  };
+}
+
+/**
+ * 归一化"两个根"的入参。
+ *
+ * 接受两种形态：
+ * - 对象 `{ libraryRoot, codeRoot }` —— 当前形态；
+ * - 字符串 —— 历史单根形态，等价于 `{ libraryRoot: str, codeRoot: str }`。
+ *
+ * 单根形态存在的意义是让"原件库与代码同目录"这种既有调用点继续成立：
+ * 解耦之后它们仍然是合法的双根组合，只是两个根指向同一个目录。
+ */
+export function normalizeRoots(input, fallback = {}) {
+  if (typeof input === 'string') {
+    const libraryRoot = path.resolve(input);
+    return {
+      libraryRoot,
+      codeRoot: path.resolve(fallback.codeRoot || libraryRoot)
+    };
+  }
+
+  const libraryRoot = path.resolve(input?.libraryRoot || fallback.libraryRoot || process.cwd());
+  const codeRoot = path.resolve(input?.codeRoot || fallback.codeRoot || libraryRoot);
+
+  return { libraryRoot, codeRoot };
+}

package/lib/skillLinkStore.js

@@ -0,0 +1,68 @@
+import { constants } from 'node:fs';
+import { access, lstat, readdir, readlink } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function scanSkillLinks(skillsDir) {
+  const entries = await safeReaddir(skillsDir);
+  const records = await Promise.all(
+    entries
+      .filter((entry) => !entry.name.startsWith('.'))
+      .map(async (entry) => {
+        const linkPath = path.join(skillsDir, entry.name);
+        const stat = await lstat(linkPath);
+
+        if (!stat.isSymbolicLink()) {
+          if (!stat.isDirectory()) return null;
+          return {
+            alias: entry.name,
+            linkPath,
+            targetPath: null,
+            isSymlink: false,
+            exists: true
+          };
+        }
+
+        const targetPath = await resolveLinkTarget(linkPath);
+        return {
+          alias: entry.name,
+          linkPath,
+          targetPath,
+          isSymlink: true,
+          exists: await pathExists(targetPath)
+        };
+      })
+  );
+
+  return records.filter(Boolean).sort((left, right) => left.alias.localeCompare(right.alias));
+}
+
+export async function resolveLinkTarget(linkPath) {
+  const target = await readlink(linkPath);
+  return path.resolve(path.dirname(linkPath), target);
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await access(targetPath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function linkPathExists(targetPath) {
+  try {
+    await lstat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeReaddir(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}