skillcaddy 0.27.0

package/lib/sourceLocalAcquisitionAdapter.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import {
+  defineSourceAcquisitionAdapter
+} from './sourceAcquisitionAdapter.js';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { inspectLocalInput, stageLocalInput } from './sourceLocal.js';
+import {
+  assertDirectorySourceMatchesRecord,
+  sameJson
+} from './sourceAcquisitionPolicy.js';
+import { validateSourceId } from './sourceRegistry.js';
+
+export function createLocalAcquisitionAdapter({ archiveLimits }, request) {
+  const inputPath = requireLocalInput(request);
+  const requestIdentity = {
+    name: request.name,
+    namespace: request.namespace
+  };
+
+  return defineSourceAcquisitionAdapter({
+    stalePlanMessage: 'Local source content changed since the add plan',
+    inspect: async () => buildLocalCandidate(
+      await inspectLocalInput(inputPath, { archiveLimits })
+    ),
+    prepare: async (workspaceRoot) => buildLocalCandidate(
+      await stageLocalInput(inputPath, workspaceRoot, { archiveLimits })
+    ),
+    resolveIdentity(candidate) {
+      return resolveLocalIdentity(requestIdentity, candidate.defaultName);
+    },
+    buildRecord(plan) {
+      return {
+        schemaVersion: 1,
+        sourceId: plan.sourceId,
+        bucket: 'personal',
+        type: 'local',
+        installPath: plan.installPath,
+        origin: {
+          kind: 'local',
+          name: plan.input.name
+        },
+        integrity: plan.integrity,
+        skills: plan.skills
+      };
+    },
+    matchesIdentity(record, plan) {
+      return record.type === 'local' &&
+        record.installPath === plan.installPath;
+    },
+    matchesContent(record, plan) {
+      return record.integrity?.value === plan.integrity.value &&
+        sameJson(record.skills, plan.skills);
+    },
+    assertInstalled: assertDirectorySourceMatchesRecord
+  });
+}
+
+function requireLocalInput(request) {
+  if (!request || typeof request.input !== 'string' || !request.input.trim()) {
+    throw new Error('Source add requires request.input');
+  }
+  return path.resolve(request.input);
+}
+
+function resolveLocalIdentity(request, defaultName) {
+  const name = request.name === undefined ? defaultName : request.name;
+  const namespace = request.namespace;
+  if (typeof name !== 'string' || !name) {
+    throw identityError('Local source name must be a non-empty identity segment');
+  }
+  if (namespace !== undefined && (typeof namespace !== 'string' || !namespace)) {
+    throw identityError('Local source namespace must be a non-empty identity segment');
+  }
+
+  const sourceId = namespace
+    ? `personal/${namespace}/${name}`
+    : `personal/${name}`;
+  try {
+    validateSourceId(sourceId);
+  } catch {
+    throw identityError(
+      `Invalid local source identity: ${sourceId}. Use --name and --namespace with safe identity segments.`
+    );
+  }
+  return {
+    sourceId,
+    installPath: `personal/${namespace ? `${namespace}--` : ''}${name}`
+  };
+}
+
+function buildLocalCandidate(prepared) {
+  return {
+    defaultName: prepared.defaultName,
+    input: {
+      type: prepared.type,
+      name: prepared.basename
+    },
+    integrity: prepared.integrity,
+    skills: prepared.skills,
+    warnings: prepared.warnings,
+    ...(prepared.contentRoot ? { contentRoot: prepared.contentRoot } : {})
+  };
+}
+
+function identityError(message) {
+  return new SourceAcquisitionError('unresolved-identity', message, 3);
+}

package/lib/sourceManager.js

@@ -0,0 +1,242 @@
+import {
+  exportLibraryImage as exportLibraryImageWorkflow,
+  importLibraryImage as importLibraryImageWorkflow
+} from './libraryImage.js';
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  applySourceAcquisition,
+  planSourceAcquisition
+} from './sourceAcquisition.js';
+import {
+  updateRegisteredGitSources
+} from './sourceGitBatchUpdate.js';
+import {
+  applyGitSourceRepair,
+  planGitSourceRepair
+} from './sourceGitRepair.js';
+import {
+  applySourceUpgrade,
+  planSourceUpgrade
+} from './sourceUpgrade.js';
+import { readSourceRecords, validateSourceId } from './sourceRegistry.js';
+import {
+  applySourceMigrationPlan,
+  buildSourceMigrationPlan
+} from './sourceMigration.js';
+import { SOURCE_FOLDERS } from './sourcePolicy.js';
+import { readSourceDirectory } from './sourceTree.js';
+
+export async function listSources(context) {
+  const rootDir = requireRootDir(context);
+  const registered = await readSourceRecords(rootDir);
+  const registeredPaths = new Set(registered.map((record) => record.installPath));
+  const unmanaged = await findUnmanagedSourceEntries(rootDir, registeredPaths);
+
+  const sources = [
+    ...await Promise.all(registered.map(async (record) => ({
+      inventoryId: record.sourceId,
+      status: 'registered',
+      sourceId: record.sourceId,
+      installPath: record.installPath,
+      exists: await pathExists(path.join(rootDir, record.installPath))
+    }))),
+    ...unmanaged
+  ];
+
+  return {
+    sources: sources.sort(compareInventoryEntries)
+  };
+}
+
+export async function inspectSource(context, sourceId) {
+  const rootDir = requireRootDir(context);
+  validateSourceId(sourceId);
+  const records = await readSourceRecords(rootDir);
+  const record = records.find((candidate) => candidate.sourceId === sourceId);
+  if (!record) throw new Error(`Source is not registered: ${sourceId}`);
+  return record;
+}
+
+export async function planSourceMigration(context) {
+  return buildSourceMigrationPlan(requireRootDir(context));
+}
+
+export async function applySourceMigration(context, plan) {
+  return applySourceMigrationPlan(requireRootDir(context), plan);
+}
+
+export async function planAddSource(context, request) {
+  return planSourceAcquisition({
+    rootDir: requireRootDir(context),
+    archiveLimits: context?.archiveLimits,
+    httpLimits: context?.httpLimits,
+    httpLookup: context?.httpLookup
+  }, request);
+}
+
+export async function applyAddSource(context, plan) {
+  return applySourceAcquisition({
+    rootDir: requireRootDir(context),
+    archiveLimits: context?.archiveLimits,
+    httpLimits: context?.httpLimits,
+    httpLookup: context?.httpLookup
+  }, plan);
+}
+
+export async function planUpdateSource(context, request) {
+  return planSourceUpgrade({
+    rootDir: requireRootDir(context),
+    archiveLimits: context?.archiveLimits,
+    httpLimits: context?.httpLimits,
+    httpLookup: context?.httpLookup,
+    projectPath: context?.projectPath,
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs
+  }, {
+    request,
+    authorization: { kind: 'ordinary' }
+  });
+}
+
+export async function planBreakingUpdateSource(context, request) {
+  return planSourceUpgrade({
+    rootDir: requireRootDir(context),
+    archiveLimits: context?.archiveLimits,
+    httpLimits: context?.httpLimits,
+    httpLookup: context?.httpLookup,
+    projectPath: context?.projectPath,
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs
+  }, {
+    request,
+    authorization: { kind: 'breaking' }
+  });
+}
+
+export async function applyUpdateSource(context, plan) {
+  const lifecycleApplication = await applySourceUpgrade({
+    rootDir: requireRootDir(context),
+    archiveLimits: context?.archiveLimits,
+    httpLimits: context?.httpLimits,
+    httpLookup: context?.httpLookup,
+    projectPath: context?.projectPath,
+    fileOperations: context?.fileOperations,
+    publishRecord: context?.publishRecord,
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs
+  }, plan);
+  if (lifecycleApplication.status === 'applied') {
+    return lifecycleApplication.result;
+  }
+}
+
+export async function updateGitSources(context, options) {
+  const projectPath = requireProjectPath(context);
+  return updateRegisteredGitSources({
+    rootDir: requireRootDir(context),
+    projectPath,
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    publishRecord: context?.publishRecord,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs,
+    gitNetworkFailureLimit: context?.gitNetworkFailureLimit
+  }, options);
+}
+
+export async function planRepairSource(context, request) {
+  return planGitSourceRepair({
+    rootDir: requireRootDir(context),
+    projectPath: requireProjectPath(context),
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs
+  }, {
+    request,
+    authorization: { kind: 'ordinary' }
+  });
+}
+
+export async function planBreakingRepairSource(context, request) {
+  return planGitSourceRepair({
+    rootDir: requireRootDir(context),
+    projectPath: requireProjectPath(context),
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs
+  }, {
+    request,
+    authorization: { kind: 'breaking' }
+  });
+}
+
+export async function applyRepairSource(context, plan) {
+  return applyGitSourceRepair({
+    rootDir: requireRootDir(context),
+    projectPath: requireProjectPath(context),
+    globalDir: context?.globalDir,
+    hermesDir: context?.hermesDir,
+    gitFetchRetryDelaysMs: context?.gitFetchRetryDelaysMs
+  }, plan);
+}
+
+async function findUnmanagedSourceEntries(rootDir, registeredPaths) {
+  const sources = [];
+  for (const bucket of SOURCE_FOLDERS) {
+    const entries = await readSourceDirectory(path.join(rootDir, bucket));
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const installPath = `${bucket}/${entry.name}`;
+      if (registeredPaths.has(installPath)) continue;
+      sources.push({
+        inventoryId: `unmanaged:${installPath}`,
+        status: 'unmanaged',
+        sourceId: null,
+        installPath,
+        exists: true
+      });
+    }
+  }
+  return sources;
+}
+
+function requireRootDir(context) {
+  if (!context || typeof context.rootDir !== 'string' || !context.rootDir.trim()) {
+    throw new Error('Source management requires context.rootDir');
+  }
+  return path.resolve(context.rootDir);
+}
+
+function requireProjectPath(context) {
+  if (!context || typeof context.projectPath !== 'string' || !context.projectPath.trim()) {
+    throw new Error('Git source updates require context.projectPath');
+  }
+  return path.resolve(context.projectPath);
+}
+
+async function pathExists(targetPath) {
+  try {
+    await lstat(targetPath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+function compareInventoryEntries(left, right) {
+  const statusOrder = { registered: 0, unmanaged: 1 };
+  return statusOrder[left.status] - statusOrder[right.status] ||
+    left.inventoryId.localeCompare(right.inventoryId);
+}
+
+export async function exportLibraryImage(context, filePath) {
+  return exportLibraryImageWorkflow({ ...context, rootDir: requireRootDir(context) }, filePath);
+}
+
+export async function importLibraryImage(context, filePath, options) {
+  return importLibraryImageWorkflow({ ...context, rootDir: requireRootDir(context) }, filePath, options);
+}

package/lib/sourceMigration.js

@@ -0,0 +1,172 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { inspectGitSource } from './sourceGit.js';
+import { SourceMigrationIssue } from './sourceMigrationIssue.js';
+import { readSourceRecords, writeSourceRecord } from './sourceRegistry.js';
+import { validateSourceRecord } from './sourceRecord.js';
+import { scanSkills } from './skillStore.js';
+import {
+  checksumDirectory,
+  findSourceEntries,
+  validateSourceTree
+} from './sourceTree.js';
+
+export async function buildSourceMigrationPlan(rootDir) {
+  const [registered, skills] = await Promise.all([
+    readSourceRecords(rootDir),
+    scanSkills(rootDir)
+  ]);
+  const registeredPaths = new Set(registered.map((record) => record.installPath));
+  const records = [];
+  const unresolved = [];
+
+  for (const entry of await findSourceEntries(rootDir)) {
+    if (registeredPaths.has(entry.installPath)) continue;
+    try {
+      const record = await buildMigrationRecord(rootDir, entry, skills);
+      records.push(validateSourceRecord(rootDir, record));
+    } catch (error) {
+      unresolved.push({
+        installPath: entry.installPath,
+        reason: resolveIssueReason(error),
+        detail: error.message
+      });
+    }
+  }
+
+  removeDuplicateIdentities(records, unresolved, registered);
+  return {
+    dryRun: true,
+    records: records.sort((left, right) => left.sourceId.localeCompare(right.sourceId)),
+    unresolved: unresolved.sort((left, right) => left.installPath.localeCompare(right.installPath))
+  };
+}
+
+export async function applySourceMigrationPlan(rootDir, plan) {
+  assertMigrationPlan(plan);
+  const registered = await readSourceRecords(rootDir);
+  const registeredById = new Map(registered.map((record) => [record.sourceId, record]));
+  const currentPlan = await buildSourceMigrationPlan(rootDir);
+  const currentById = new Map(currentPlan.records.map((record) => [record.sourceId, record]));
+  const pending = [];
+  const unchanged = [];
+
+  for (const requestedRecord of plan.records) {
+    const validated = validateSourceRecord(rootDir, requestedRecord);
+    const existing = registeredById.get(validated.sourceId);
+    if (existing) {
+      if (!recordsEqual(existing, validated)) {
+        throw new Error(`Source migration plan conflicts with registered source: ${validated.sourceId}`);
+      }
+      unchanged.push(validated.sourceId);
+      continue;
+    }
+
+    const current = currentById.get(validated.sourceId);
+    if (!current || !recordsEqual(current, validated)) {
+      throw new Error(`Source migration plan is stale for: ${validated.sourceId}`);
+    }
+    pending.push(validated);
+  }
+
+  for (const record of pending) await writeSourceRecord(rootDir, record);
+  return {
+    dryRun: false,
+    written: pending.map((record) => record.sourceId),
+    unchanged,
+    unresolved: plan.unresolved
+  };
+}
+
+async function buildMigrationRecord(rootDir, entry, skills) {
+  if (entry.unsafe) {
+    throw new SourceMigrationIssue('unsafe-path', 'Source entry is a symbolic link');
+  }
+  await validateSourceTree(rootDir, entry.sourcePath);
+  const discoveredSkills = discoverEntrySkills(rootDir, entry.installPath, skills);
+  if (discoveredSkills.length === 0) {
+    throw new Error('No skills discovered by the existing state scanner');
+  }
+
+  try {
+    return await buildGitRecord(entry, discoveredSkills);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return buildLegacyLocalRecord(entry, discoveredSkills);
+}
+
+async function buildGitRecord(entry, discoveredSkills) {
+  await access(path.join(entry.sourcePath, '.git'));
+  const git = await inspectGitSource(entry.sourcePath);
+  return {
+    schemaVersion: 1,
+    sourceId: git.sourceId,
+    bucket: 'github',
+    type: 'git',
+    installPath: entry.installPath,
+    origin: git.origin,
+    skills: discoveredSkills
+  };
+}
+
+async function buildLegacyLocalRecord(entry, discoveredSkills) {
+  return {
+    schemaVersion: 1,
+    sourceId: entry.installPath,
+    bucket: entry.bucket,
+    type: 'legacy-local',
+    installPath: entry.installPath,
+    origin: { kind: 'unknown' },
+    integrity: {
+      algorithm: 'sha256',
+      value: await checksumDirectory(entry.sourcePath)
+    },
+    skills: discoveredSkills
+  };
+}
+
+function discoverEntrySkills(rootDir, installPath, skills) {
+  const sourcePath = path.join(rootDir, installPath);
+  return skills
+    .map((skill) => path.relative(sourcePath, skill.path))
+    .filter((relative) => !relative.startsWith('..') && !path.isAbsolute(relative))
+    .map((relative) => relative ? relative.split(path.sep).join('/') : '.')
+    .sort();
+}
+
+function removeDuplicateIdentities(records, unresolved, registered) {
+  const pathsById = new Map();
+  for (const record of [...registered, ...records]) {
+    const paths = pathsById.get(record.sourceId) || [];
+    paths.push(record.installPath);
+    pathsById.set(record.sourceId, paths);
+  }
+
+  for (let index = records.length - 1; index >= 0; index -= 1) {
+    const record = records[index];
+    const paths = [...new Set(pathsById.get(record.sourceId))];
+    if (paths.length < 2) continue;
+    records.splice(index, 1);
+    unresolved.push({
+      installPath: record.installPath,
+      reason: 'duplicate-identity',
+      detail: `Source identity ${record.sourceId} also resolves from: ${paths.join(', ')}`
+    });
+  }
+}
+
+function resolveIssueReason(error) {
+  if (error.reason) return error.reason;
+  return /Invalid sourceId/.test(error.message) ? 'invalid-identity' : 'unresolved-source';
+}
+
+function assertMigrationPlan(plan) {
+  if (!plan || plan.dryRun !== true || !Array.isArray(plan.records) || !Array.isArray(plan.unresolved)) {
+    throw new Error('A source migration plan is required');
+  }
+}
+
+function recordsEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}

package/lib/sourceMigrationIssue.js

@@ -0,0 +1,6 @@
+export class SourceMigrationIssue extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+  }
+}

package/lib/sourcePath.js

@@ -0,0 +1,6 @@
+import path from 'node:path';
+
+export function isPathInsideOrEqual(rootDir, targetPath) {
+  const relative = path.relative(rootDir, targetPath);
+  return !relative.startsWith('..') && !path.isAbsolute(relative);
+}

package/lib/sourcePolicy.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { normalizeRoots } from './roots.js';
+
+export const SOURCE_FOLDERS = ['official', 'github', 'personal', 'archived'];
+export const SOURCE_INSTALLING_MARKER = '.skillcaddy-installing';
+export const SOURCE_INSTALLING_MARKER_CONTENT = 'skillcaddy-source-publication-v1\n';
+export const REPOSITORY_SKILLS_SOURCE = 'local';
+export const REPOSITORY_SKILLS_FOLDER = 'skills';
+
+/**
+ * 允许的 skill 来源目录。
+ *
+ * 四个 source bucket 位于原件库根；仓库自带 skills 桶位于代码根。
+ * 两者解耦之后，`npx skillcaddy` 形态下仓库自带 skills 仍然可被识别、可被启用。
+ */
+function allowedSourcePaths(roots) {
+  const { libraryRoot, codeRoot } = normalizeRoots(roots);
+
+  return [
+    ...SOURCE_FOLDERS.map((sourceFolder) => ({
+      sourceFolder,
+      sourcePath: path.join(libraryRoot, sourceFolder)
+    })),
+    {
+      sourceFolder: REPOSITORY_SKILLS_FOLDER,
+      sourcePath: path.join(codeRoot, REPOSITORY_SKILLS_FOLDER)
+    }
+  ];
+}
+
+export function assertInsideAllowedSkillSources(roots, skillPath) {
+  if (isInsideAllowedSkillSources(roots, skillPath)) return;
+  throw new Error('skillPath 必须位于当前 AISkills 的来源目录或仓库 skills 目录内');
+}
+
+export function isInsideAllowedSkillSources(roots, skillPath) {
+  return Boolean(resolveAllowedSkillSource(roots, skillPath));
+}
+
+export function resolveAllowedSkillSource(roots, skillPath) {
+  for (const { sourceFolder, sourcePath } of allowedSourcePaths(roots)) {
+    const relative = path.relative(sourcePath, skillPath);
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return {
+        sourceFolder,
+        sourcePath,
+        relativePath: relative
+      };
+    }
+  }
+
+  return null;
+}