awesome-agents 0.1.5 → 0.1.6

package/src/skills.js

@@ -0,0 +1,397 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+import { expandHome, materializeSource } from "./source.js";
+
+const SKILL_CONTAINER_DIRS = [
+  "skills",
+  "skills/.curated",
+  "skills/.experimental",
+  "skills/.system",
+  ".agents/skills",
+  ".claude/skills",
+  ".codex/skills",
+  ".opencode/skills"
+];
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", "__pycache__"]);
+
+export async function installProfileSkills(profile, sourceRoot, options = {}) {
+  const dependencies = normalizeSkillDependencies(profile.attributes.skills);
+  if (dependencies.length === 0) {
+    return [];
+  }
+
+  const home = path.resolve(expandHome(options.home ?? os.homedir()));
+  const installed = [];
+
+  for (const dependency of dependencies) {
+    const skill = await resolveSkillDependency(profile, dependency, sourceRoot, home, options);
+    const target = path.join(home, ".agents", "homes", profile.slug, "skills", skill.installName);
+
+    if (!options.dryRun) {
+      await fs.rm(target, { recursive: true, force: true });
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.cp(skill.path, target, {
+        recursive: true,
+        dereference: true,
+        preserveTimestamps: true
+      });
+    }
+
+    installed.push({
+      name: skill.installName,
+      declaredName: dependency.selector ?? dependency.source ?? skill.name,
+      source: skill.source,
+      sourceKind: skill.sourceKind,
+      path: target
+    });
+  }
+
+  return installed;
+}
+
+function normalizeSkillDependencies(value) {
+  if (!value) {
+    return [];
+  }
+
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.map(parseSkillDependency);
+}
+
+function parseSkillDependency(value) {
+  if (typeof value === "string") {
+    const text = value.trim();
+    if (!text) {
+      throw new Error("Skill dependency entries must not be empty.");
+    }
+
+    const split = text.match(/^(\S+)\s+(.+)$/);
+    if (split) {
+      return { source: split[1], selector: split[2].trim(), raw: text };
+    }
+
+    const atSelector = splitAtSelector(text);
+    if (atSelector) {
+      return { source: atSelector.source, selector: atSelector.selector, raw: text };
+    }
+
+    if (looksLikeRemoteSource(text)) {
+      return { source: text, selector: undefined, raw: text };
+    }
+
+    return { selector: text, raw: text };
+  }
+
+  if (isObject(value)) {
+    const source = firstString(value.source, value.package, value.repository, value.repo);
+    const selector = firstString(value.skill, value.name, value.slug, value.id);
+    if (!source && !selector) {
+      throw new Error("Skill dependency objects must include a skill/name or source field.");
+    }
+    return { source, selector, raw: value };
+  }
+
+  throw new Error("Skill dependencies must be strings or objects.");
+}
+
+function splitAtSelector(value) {
+  if (value.startsWith("git@")) {
+    return undefined;
+  }
+  const atIndex = value.lastIndexOf("@");
+  if (atIndex <= 0 || atIndex === value.length - 1 || atIndex <= value.lastIndexOf("/")) {
+    return undefined;
+  }
+  return {
+    source: value.slice(0, atIndex),
+    selector: value.slice(atIndex + 1)
+  };
+}
+
+function looksLikeRemoteSource(value) {
+  return value.includes("/") || value.includes(":") || value.startsWith("~") || value.startsWith(".");
+}
+
+async function resolveSkillDependency(profile, dependency, sourceRoot, home, options) {
+  if (dependency.source) {
+    const materialized = await materializeSource(dependency.source, {
+      ...options,
+      requireAgentProfileLayout: false
+    });
+    try {
+      return await selectSkillFromRoot(materialized.path, dependency.selector, {
+        dependency,
+        source: materialized.source,
+        sourceKind: materialized.kind
+      });
+    } finally {
+      await materialized.cleanup();
+    }
+  }
+
+  const profileSkill = await findSkillInRoot(profile.agentRoot, dependency.selector, {
+    dependency,
+    source: profile.agentRoot,
+    sourceKind: "profile-local"
+  });
+  if (profileSkill) {
+    return profileSkill;
+  }
+
+  const sourceSkill = await findSkillInRoot(sourceRoot, dependency.selector, {
+    dependency,
+    source: sourceRoot,
+    sourceKind: "local-source"
+  });
+  if (sourceSkill) {
+    return sourceSkill;
+  }
+
+  const userSkillRoot = path.join(home, ".agents", "skills");
+  const userSkill = await findSkillInRoot(userSkillRoot, dependency.selector, {
+    dependency,
+    source: userSkillRoot,
+    sourceKind: "user-skills"
+  });
+  if (userSkill) {
+    return userSkill;
+  }
+
+  throw new Error(`Skill "${dependency.selector}" was not found in the profile source or ${userSkillRoot}.`);
+}
+
+async function findSkillInRoot(root, selector, context) {
+  if (!root || !existsSync(root)) {
+    return undefined;
+  }
+
+  const skills = await discoverSkills(root);
+  if (skills.length === 0) {
+    return undefined;
+  }
+
+  return findDiscoveredSkill(skills, selector, context);
+}
+
+async function selectSkillFromRoot(root, selector, context) {
+  const skills = await discoverSkills(root);
+  if (skills.length === 0) {
+    throw new Error(`No skills found in ${context.source}. Expected SKILL.md files in the source root or skills/<name>/.`);
+  }
+
+  return selectDiscoveredSkill(skills, selector, context);
+}
+
+function selectDiscoveredSkill(skills, selector, context) {
+  if (!selector) {
+    if (skills.length === 1) {
+      return withSource(skills[0], context);
+    }
+    throw new Error(`Skill source "${context.source}" contains multiple skills. Specify one of: ${skills.map((skill) => skill.name).join(", ")}`);
+  }
+
+  const normalized = sanitizeSkillName(selector);
+  const selected = skills.find((skill) => {
+    return sanitizeSkillName(skill.name) === normalized
+      || sanitizeSkillName(skill.directoryName) === normalized
+      || skill.installName === normalized;
+  });
+
+  if (!selected) {
+    throw new Error(`Skill "${selector}" was not found in ${context.source}. Available skills: ${skills.map((skill) => skill.name).join(", ")}`);
+  }
+
+  return withSource(selected, context);
+}
+
+function findDiscoveredSkill(skills, selector, context) {
+  if (!selector) {
+    return skills.length === 1 ? withSource(skills[0], context) : undefined;
+  }
+
+  const normalized = sanitizeSkillName(selector);
+  const selected = skills.find((skill) => {
+    return sanitizeSkillName(skill.name) === normalized
+      || sanitizeSkillName(skill.directoryName) === normalized
+      || skill.installName === normalized;
+  });
+
+  return selected ? withSource(selected, context) : undefined;
+}
+
+function withSource(skill, context) {
+  return {
+    ...skill,
+    source: context.source,
+    sourceKind: context.sourceKind
+  };
+}
+
+async function discoverSkills(root) {
+  const discovered = [];
+  const seenPaths = new Set();
+  const seenNames = new Set();
+
+  const addSkillAt = async (skillDir) => {
+    const skillPath = path.join(skillDir, "SKILL.md");
+    if (!existsSync(skillPath)) {
+      return false;
+    }
+
+    const resolved = path.resolve(skillDir);
+    if (seenPaths.has(resolved)) {
+      return true;
+    }
+
+    const skill = await readSkill(skillDir, root);
+    if (seenNames.has(skill.installName)) {
+      return true;
+    }
+
+    discovered.push(skill);
+    seenPaths.add(resolved);
+    seenNames.add(skill.installName);
+    return true;
+  };
+
+  await addSkillAt(root);
+  await discoverContainer(root, false, addSkillAt);
+  for (const container of SKILL_CONTAINER_DIRS) {
+    await discoverContainer(path.join(root, container), true, addSkillAt);
+  }
+
+  if (discovered.length === 0) {
+    for (const skillDir of await findSkillDirs(root)) {
+      await addSkillAt(skillDir);
+    }
+  }
+
+  return discovered.sort((a, b) => a.installName.localeCompare(b.installName));
+}
+
+async function discoverContainer(container, walkGrandchildren, addSkillAt) {
+  let entries;
+  try {
+    entries = await fs.readdir(container, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) {
+      continue;
+    }
+
+    const childDir = path.join(container, entry.name);
+    if (!await isDirectoryLike(entry, childDir)) {
+      continue;
+    }
+
+    const found = await addSkillAt(childDir);
+    if (found || !walkGrandchildren) {
+      continue;
+    }
+
+    let grandchildren;
+    try {
+      grandchildren = await fs.readdir(childDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const grandchild of grandchildren) {
+      if (SKIP_DIRS.has(grandchild.name)) {
+        continue;
+      }
+      const grandchildDir = path.join(childDir, grandchild.name);
+      if (await isDirectoryLike(grandchild, grandchildDir)) {
+        await addSkillAt(grandchildDir);
+      }
+    }
+  }
+}
+
+async function findSkillDirs(root) {
+  const results = [];
+
+  async function visit(directory) {
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    if (existsSync(path.join(directory, "SKILL.md"))) {
+      results.push(directory);
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      const entryPath = path.join(directory, entry.name);
+      if (await isDirectoryLike(entry, entryPath)) {
+        await visit(entryPath);
+      }
+    }
+  }
+
+  await visit(root);
+  return results;
+}
+
+async function readSkill(skillDir, root) {
+  const skillPath = path.join(skillDir, "SKILL.md");
+  const raw = await fs.readFile(skillPath, "utf8");
+  const parsed = parseFrontmatter(raw, skillPath);
+  const directoryName = path.basename(skillDir);
+  const name = firstString(parsed.attributes.name, directoryName);
+
+  return {
+    name,
+    installName: sanitizeSkillName(name),
+    directoryName,
+    path: skillDir,
+    relativePath: path.relative(root, skillDir)
+  };
+}
+
+async function isDirectoryLike(entry, entryPath) {
+  if (entry.isDirectory()) {
+    return true;
+  }
+  if (!entry.isSymbolicLink()) {
+    return false;
+  }
+
+  try {
+    return (await fs.stat(entryPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function sanitizeSkillName(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9._]+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "")
+    .slice(0, 255) || "unnamed-skill";
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return "";
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/source.js

@@ -90,6 +90,7 @@ export function normalizeGithubUrl(source) {
 export async function materializeSource(sourceInput, options = {}) {
   const home = options.home ?? os.homedir();
   const source = sourceInput;
+  const requireAgentProfileLayout = options.requireAgentProfileLayout ?? true;
 
   if (!source) {
     throw new Error("Specify a source. Use a local path, owner/repo, or GitHub URL.");
@@ -97,7 +98,9 @@ export async function materializeSource(sourceInput, options = {}) {
 
   if (isLocalSource(source, home)) {
     const sourcePath = path.resolve(expandHome(source, home));
-    await assertAgentProfileLayout(sourcePath);
+    if (requireAgentProfileLayout) {
+      await assertAgentProfileLayout(sourcePath);
+    }
     return {
       kind: "local",
       source: sourcePath,
@@ -106,14 +109,20 @@ export async function materializeSource(sourceInput, options = {}) {
     };
   }
 
-  const gitUrl = normalizeGithubUrl(source);
+  const { sourceWithoutRef, ref } = splitGitRef(source);
+  const gitUrl = normalizeGithubUrl(sourceWithoutRef);
   if (!gitUrl) {
     throw new Error(`Unsupported source "${source}". Use a local path, owner/repo, or GitHub URL.`);
   }
 
   const tmpRoot = options.tmpRoot ?? os.tmpdir();
   const cloneDir = await fs.mkdtemp(path.join(tmpRoot, "awesome-agents-source-"));
-  const clone = spawnSync("git", ["clone", "--depth=1", gitUrl, cloneDir], {
+  const cloneArgs = ["clone", "--depth=1"];
+  if (ref) {
+    cloneArgs.push("--branch", ref);
+  }
+  cloneArgs.push(gitUrl, cloneDir);
+  const clone = spawnSync("git", cloneArgs, {
     encoding: "utf8"
   });
 
@@ -123,7 +132,9 @@ export async function materializeSource(sourceInput, options = {}) {
     throw new Error(`Could not clone ${source}: ${detail}`);
   }
 
-  await assertAgentProfileLayout(cloneDir);
+  if (requireAgentProfileLayout) {
+    await assertAgentProfileLayout(cloneDir);
+  }
 
   return {
     kind: "git",
@@ -136,6 +147,17 @@ export async function materializeSource(sourceInput, options = {}) {
   };
 }
 
+function splitGitRef(source) {
+  const hashIndex = source.lastIndexOf("#");
+  if (hashIndex <= 0 || hashIndex === source.length - 1) {
+    return { sourceWithoutRef: source, ref: undefined };
+  }
+  return {
+    sourceWithoutRef: source.slice(0, hashIndex),
+    ref: source.slice(hashIndex + 1)
+  };
+}
+
 async function assertAgentProfileLayout(sourcePath) {
   const entries = await discoverProfileEntries(sourcePath);
   if (entries.length === 0) {