skillcaddy 0.27.0

package/lib/sourceRemoteFilePolicy.js

@@ -0,0 +1,62 @@
+const GITHUB_HOSTNAMES = new Set(['github.com', 'www.github.com']);
+
+export function isRemoteSkillFilePathInput(input) {
+  const url = parseUrl(input);
+  return Boolean(
+    url &&
+    ['http:', 'https:'].includes(url.protocol) &&
+    url.pathname.endsWith('/SKILL.md')
+  );
+}
+
+export function isGitHubBlobSkillFileInput(input) {
+  const url = parseUrl(input);
+  return Boolean(
+    url &&
+    GITHUB_HOSTNAMES.has(url.hostname.toLowerCase()) &&
+    url.pathname.endsWith('/SKILL.md') &&
+    url.pathname.split('/').includes('blob')
+  );
+}
+
+export function validateRemoteSkillFileUrl(input, options = {}) {
+  const url = parseUrl(input);
+  if (!url || !['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Remote file source input must be a valid HTTP(S) URL');
+  }
+  if (url.username || url.password) {
+    throw new Error('Remote file source URL must not contain credentials');
+  }
+  if (url.search) {
+    throw new Error('Remote file source URL must not contain a query');
+  }
+  if (!url.pathname.endsWith('/SKILL.md')) {
+    throw new Error('Remote file source URL path must end with /SKILL.md');
+  }
+  if (isGitHubBlobSkillFileInput(url)) {
+    throw new Error('Remote file source requires a direct SKILL.md URL');
+  }
+  if (!options.allowFragment && url.hash) {
+    throw new Error('Remote file source URL must not contain a fragment');
+  }
+
+  const sanitized = new URL(url);
+  sanitized.username = '';
+  sanitized.password = '';
+  sanitized.search = '';
+  sanitized.hash = '';
+  return {
+    url,
+    display: sanitized.toString(),
+    protocol: url.protocol.slice(0, -1)
+  };
+}
+
+function parseUrl(input) {
+  if (typeof input !== 'string' && !(input instanceof URL)) return null;
+  try {
+    return new URL(input.toString().trim());
+  } catch {
+    return null;
+  }
+}

package/lib/sourceRemoteFileWorkspace.js

@@ -0,0 +1,55 @@
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { downloadRemoteSkillFile } from './sourceHttp.js';
+import { checksumDirectory } from './sourceTree.js';
+import { validateStagedSource } from './sourceValidation.js';
+
+export async function inspectRemoteSkillFile(context, parsed, prefix) {
+  const stagingRoot = await mkdtemp(path.join(tmpdir(), prefix));
+  try {
+    return await stageRemoteSkillFile(context, parsed, stagingRoot);
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+  }
+}
+
+export async function stageRemoteSkillFile(context, parsed, stagingRoot) {
+  const contentRoot = path.join(stagingRoot, 'content');
+  await mkdir(contentRoot);
+  const skillFile = path.join(contentRoot, 'SKILL.md');
+  await downloadRemoteSkillFile(parsed.input, skillFile, {
+    limits: context.httpLimits,
+    lookup: context.httpLookup
+  });
+  await validateRemoteSkillFileBytes(skillFile);
+  const validated = await validateStagedSource(contentRoot);
+  return {
+    contentRoot,
+    integrity: {
+      algorithm: 'sha256',
+      value: await checksumDirectory(contentRoot)
+    },
+    skills: validated.skills,
+    warnings: validated.warnings
+  };
+}
+
+async function validateRemoteSkillFileBytes(skillFile) {
+  const content = await readFile(skillFile);
+  if (content.includes(0)) {
+    throw new SourceAcquisitionError(
+      'source-validation',
+      'Remote SKILL.md must not contain NUL bytes'
+    );
+  }
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(content);
+  } catch {
+    throw new SourceAcquisitionError(
+      'source-validation',
+      'Remote SKILL.md must contain valid UTF-8'
+    );
+  }
+}

package/lib/sourceSkillDiscovery.js

@@ -0,0 +1,117 @@
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const EXCLUDED_SKILL_DIRECTORIES = new Set(['docs', 'references', 'tests']);
+const MAX_SKILL_DISCOVERY_DEPTH = 4;
+
+export async function discoverSourceSkillDirectories(sourceRoot) {
+  if (await pathEntryExists(path.join(sourceRoot, 'SKILL.md'))) return [sourceRoot];
+
+  const skillsRoot = path.join(sourceRoot, 'skills');
+  if (await directoryExists(skillsRoot)) {
+    const standardSkills = await findNestedSkillDirectories(
+      skillsRoot,
+      MAX_SKILL_DISCOVERY_DEPTH
+    );
+    if (standardSkills.length > 0) return standardSkills;
+  }
+
+  // Agent Skills 标准容器: `.agents/skills/`
+  // 这是 Anthropic 等多 agent 工具约定的官方位置；当仓库既没有 `skills/`
+  // 也没有 plugin-style `<name>/skills/` 集合，但仍然遵循该约定时，识别
+  // 这里的 skill。该位置优先级低于 `skills/`，仅作为第二标准容器。
+  const agentSkillsRoot = path.join(sourceRoot, '.agents', 'skills');
+  if (await directoryExists(agentSkillsRoot)) {
+    const agentSkills = await findNestedSkillDirectories(
+      agentSkillsRoot,
+      MAX_SKILL_DISCOVERY_DEPTH
+    );
+    if (agentSkills.length > 0) return agentSkills;
+  }
+
+  const collectionSkills = await findCollectionSkillDirectories(sourceRoot);
+  if (collectionSkills.length > 0) return collectionSkills;
+
+  const fallbackSkills = [];
+  const singularSkillRoot = path.join(sourceRoot, 'skill');
+  if (await directoryExists(singularSkillRoot)) {
+    fallbackSkills.push(...await findNestedSkillDirectories(
+      singularSkillRoot,
+      MAX_SKILL_DISCOVERY_DEPTH
+    ));
+  }
+  fallbackSkills.push(...await findDirectSkillDirectories(sourceRoot));
+
+  return [...new Set(fallbackSkills)].sort((left, right) => left.localeCompare(right));
+}
+
+async function findCollectionSkillDirectories(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (
+      !entry.isDirectory() ||
+      entry.name.startsWith('.') ||
+      EXCLUDED_SKILL_DIRECTORIES.has(entry.name) ||
+      ['skill', 'skills'].includes(entry.name)
+    ) continue;
+    const collectionSkillsRoot = path.join(directory, entry.name, 'skills');
+    if (!await directoryExists(collectionSkillsRoot)) continue;
+    skills.push(...await findNestedSkillDirectories(
+      collectionSkillsRoot,
+      MAX_SKILL_DISCOVERY_DEPTH
+    ));
+  }
+  return skills;
+}
+
+async function findNestedSkillDirectories(directory, depth) {
+  if (depth < 0) return [];
+  if (await pathEntryExists(path.join(directory, 'SKILL.md'))) return [directory];
+
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (
+      !entry.isDirectory() ||
+      entry.name.startsWith('.') ||
+      EXCLUDED_SKILL_DIRECTORIES.has(entry.name)
+    ) continue;
+    nested.push(...await findNestedSkillDirectories(path.join(directory, entry.name), depth - 1));
+  }
+  return nested;
+}
+
+async function findDirectSkillDirectories(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (
+      !entry.isDirectory() ||
+      entry.name.startsWith('.') ||
+      EXCLUDED_SKILL_DIRECTORIES.has(entry.name)
+    ) continue;
+    const candidate = path.join(directory, entry.name);
+    if (await pathEntryExists(path.join(candidate, 'SKILL.md'))) skills.push(candidate);
+  }
+  return skills;
+}
+
+async function pathEntryExists(targetPath) {
+  try {
+    await lstat(targetPath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function directoryExists(targetPath) {
+  try {
+    return (await lstat(targetPath)).isDirectory();
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}

package/lib/sourceTree.js

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto';
+import {
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  readlink,
+  realpath
+} from 'node:fs/promises';
+import path from 'node:path';
+import { SourceMigrationIssue } from './sourceMigrationIssue.js';
+import { isPathInsideOrEqual } from './sourcePath.js';
+import { SOURCE_FOLDERS } from './sourcePolicy.js';
+
+export async function findSourceEntries(rootDir) {
+  const entries = [];
+  for (const bucket of SOURCE_FOLDERS) {
+    const bucketPath = path.join(rootDir, bucket);
+    for (const entry of await readSourceDirectory(bucketPath)) {
+      if (entry.isDirectory() || entry.isSymbolicLink()) {
+        entries.push({
+          bucket,
+          installPath: `${bucket}/${entry.name}`,
+          sourcePath: path.join(bucketPath, entry.name),
+          unsafe: entry.isSymbolicLink()
+        });
+      }
+    }
+  }
+  return entries;
+}
+
+export async function validateSourceTree(rootDir, sourcePath) {
+  const [resolvedRoot, resolvedSource] = await Promise.all([
+    realpath(path.resolve(rootDir)),
+    realpath(sourcePath)
+  ]);
+  if (!isPathInsideOrEqual(resolvedRoot, resolvedSource)) {
+    throw new SourceMigrationIssue('unsafe-path', 'Source path resolves outside the central-library root');
+  }
+
+  async function walk(directory, relativeDirectory = '') {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(directory, entry.name);
+      const relativePath = path.posix.join(relativeDirectory, entry.name);
+      if (entry.name === '.git') {
+        if (entry.isSymbolicLink()) {
+          throw new SourceMigrationIssue('unsafe-path', `Git metadata is a symbolic link: ${relativePath}`);
+        }
+        if (relativeDirectory) {
+          throw new SourceMigrationIssue('nested-repository', `Nested Git repository: ${relativePath}`);
+        }
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await walk(entryPath, relativePath);
+      } else if (entry.isSymbolicLink()) {
+        await validateSymlink(resolvedSource, entryPath, relativePath);
+      } else if (!entry.isFile()) {
+        const stat = await lstat(entryPath);
+        throw new SourceMigrationIssue('unsafe-path', `Unsupported entry mode ${stat.mode}: ${relativePath}`);
+      }
+    }
+  }
+
+  await walk(sourcePath);
+}
+
+export async function checksumDirectory(directory) {
+  return checksumDirectoryWithOptions(directory, false);
+}
+
+/**
+ * Compute the image-side checksum after applying the NFC path policy from
+ * ADR-0011/#35. The ordinary checksum remains unchanged for existing source
+ * acquisition and registry contracts.
+ */
+export async function checksumDirectoryNormalized(directory) {
+  return checksumDirectoryWithOptions(directory, true);
+}
+
+async function checksumDirectoryWithOptions(directory, normalizePaths) {
+  const hash = createHash('sha256');
+
+  async function walk(currentPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => {
+      const leftName = normalizePaths ? left.name.normalize('NFC') : left.name;
+      const rightName = normalizePaths ? right.name.normalize('NFC') : right.name;
+      return leftName.localeCompare(rightName) || left.name.localeCompare(right.name);
+    })) {
+      const entryPath = path.join(currentPath, entry.name);
+      const relativePath = path.relative(directory, entryPath)
+        .split(path.sep)
+        .join('/');
+      const hashedPath = normalizePaths ? relativePath.normalize('NFC') : relativePath;
+      if (entry.isDirectory()) {
+        hash.update(`directory\0${hashedPath}\0`);
+        await walk(entryPath);
+      } else if (entry.isFile()) {
+        hash.update(`file\0${hashedPath}\0`);
+        hash.update(await readFile(entryPath));
+        hash.update('\0');
+      } else if (entry.isSymbolicLink()) {
+        const target = await readlink(entryPath);
+        hash.update(`symlink\0${hashedPath}\0${normalizePaths ? target.normalize('NFC') : target}\0`);
+      } else {
+        throw new Error(`Unsupported source entry: ${hashedPath}`);
+      }
+    }
+  }
+
+  await walk(directory);
+  return hash.digest('hex');
+}
+
+export async function readSourceDirectory(directory) {
+  try {
+    return await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+export async function sourcePathExists(targetPath) {
+  try {
+    await lstat(targetPath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function sourceInstallPathAvailable(rootDir, records, installPath) {
+  return !records.some((record) => record.installPath === installPath) &&
+    !await sourcePathExists(path.join(rootDir, ...installPath.split('/')));
+}
+
+export async function ensureSourceDirectory(rootDir, ...segments) {
+  let current = await realpath(path.resolve(rootDir));
+  const resolvedRoot = current;
+
+  for (const segment of segments) {
+    if (!segment || segment.includes('/') || segment.includes('\\')) {
+      throw new Error('Invalid managed source directory segment');
+    }
+    const next = path.join(current, segment);
+    let stat;
+    try {
+      stat = await lstat(next);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await mkdir(next);
+      stat = await lstat(next);
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error(`Managed source directory is not a safe directory: ${segment}`);
+    }
+    current = await realpath(next);
+    if (!isPathInsideOrEqual(resolvedRoot, current)) {
+      throw new Error(`Managed source directory resolves outside the central-library root: ${segment}`);
+    }
+  }
+  return current;
+}
+
+async function validateSymlink(resolvedSource, entryPath, relativePath) {
+  const target = await readlink(entryPath);
+  if (path.isAbsolute(target)) {
+    throw new SourceMigrationIssue('unsafe-path', `Absolute symlink: ${relativePath}`);
+  }
+
+  let resolvedTarget;
+  try {
+    resolvedTarget = await realpath(entryPath);
+  } catch {
+    throw new SourceMigrationIssue('unsafe-path', `Broken symlink: ${relativePath}`);
+  }
+  if (!isPathInsideOrEqual(resolvedSource, resolvedTarget)) {
+    throw new SourceMigrationIssue('unsafe-path', `Escaping symlink: ${relativePath}`);
+  }
+}