agentic-awesome-skills 14.0.0

package/tools/lib/project-root.js

@@ -0,0 +1,25 @@
+const fs = require("fs");
+const path = require("path");
+
+function findProjectRoot(startDir = __dirname) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (
+      fs.existsSync(path.join(current, "package.json")) &&
+      fs.existsSync(path.join(current, "README.md"))
+    ) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error(`Could not locate project root from ${startDir}`);
+    }
+    current = parent;
+  }
+}
+
+module.exports = {
+  findProjectRoot,
+};

package/tools/lib/skill-filter.js

@@ -0,0 +1,110 @@
+/**
+ * Skill Filtering Utility - Fixes Issue #215 (Gemini Token Truncation)
+ * 
+ * This module provides utilities to filter and manage skills by category,
+ * reducing context overhead when all skills exceed token limits.
+ * 
+ * Issue: When all 1,200+ skills are loaded, they collectively exceed Gemini's
+ * token limit for chat message conversion, causing truncation errors.
+ * 
+ * Solution: Filter skills by category to reduce context size
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Skill categories and their typical token weights (estimated)
+const SKILL_CATEGORIES = {
+  'core': { description: 'Essential/core skills', weight: 0.5 },
+  'ai-agents': { description: 'AI agents and multi-agent patterns', weight: 1.0 },
+  'architecture': { description: 'System architecture and design', weight: 0.8 },
+  'frontend': { description: 'Frontend development', weight: 0.7 },
+  'backend': { description: 'Backend development', weight: 0.7 },
+  'devops': { description: 'DevOps and infrastructure', weight: 0.9 },
+  'security': { description: 'Security and auditing', weight: 0.8 },
+  'testing': { description: 'Testing strategies', weight: 0.6 },
+  'documentation': { description: 'Documentation and technical writing', weight: 0.5 },
+  'performance': { description: 'Performance optimization', weight: 0.6 }
+};
+
+// Recommended bundles for different token limits
+const SKILL_BUNDLES = {
+  'minimal': {
+    description: 'Minimal bundle for Gemini (solves issue #215)',
+    categories: ['development', 'devops'],
+    estimatedTokens: 5000,
+    note: 'Recommended for environments with strict token limits'
+  },
+  'balanced': {
+    description: 'Balanced bundle with essential and development skills',
+    categories: ['development', 'devops', 'security', 'documentation'],
+    estimatedTokens: 15000,
+    note: 'Good for most development scenarios'
+  },
+  'complete': {
+    description: 'Complete bundle with all skill categories',
+    categories: Object.keys(SKILL_CATEGORIES),
+    estimatedTokens: 50000,
+    note: 'Full suite - may exceed token limits on some models'
+  }
+};
+
+/**
+ * Filter skills by category
+ * @param {Array} skills - Array of skill objects
+ * @param {Array} categories - Array of category names to include
+ * @returns {Array} Filtered skills
+ */
+function filterSkillsByCategory(skills, categories = ['core']) {
+  if (!Array.isArray(skills)) return [];
+  if (!Array.isArray(categories) || categories.length === 0) {
+    categories = ['core'];
+  }
+  
+  return skills.filter(skill => {
+    const skillCategory = skill.category || skill.tags?.[0];
+    return categories.includes(skillCategory);
+  });
+}
+
+/**
+ * Get skills by bundle name
+ * @param {Array} skills - Array of skill objects
+ * @param {String} bundleName - Bundle name (minimal, balanced, complete)
+ * @returns {Array} Skills matching the bundle
+ */
+function getSkillsByBundle(skills, bundleName = 'minimal') {
+  if (!Array.isArray(skills)) return [];
+
+  if (bundleName === 'complete') {
+    return [...skills];
+  }
+
+  const bundle = SKILL_BUNDLES[bundleName];
+  if (!bundle) {
+    console.warn(`Unknown bundle: ${bundleName}. Using 'minimal' bundle.`);
+    return filterSkillsByCategory(skills, SKILL_BUNDLES['minimal'].categories);
+  }
+  
+  return filterSkillsByCategory(skills, bundle.categories);
+}
+
+/**
+ * Get bundle info and recommendations
+ * @returns {Object} Bundle information
+ */
+function getBundleInfo() {
+  return {
+    bundles: SKILL_BUNDLES,
+    categories: SKILL_CATEGORIES,
+    recommendation: 'Use "minimal" or "balanced" bundle for Gemini to avoid token truncation errors (#215)'
+  };
+}
+
+module.exports = {
+  SKILL_CATEGORIES,
+  SKILL_BUNDLES,
+  filterSkillsByCategory,
+  getSkillsByBundle,
+  getBundleInfo
+};

package/tools/lib/skill-utils.js

@@ -0,0 +1,226 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+function isSafeDirectory(dirPath) {
+  try {
+    const stats = fs.lstatSync(dirPath);
+    return stats.isDirectory() && !stats.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function isSafeSkillFile(skillPath) {
+  try {
+    const stats = fs.lstatSync(skillPath);
+    return stats.isFile() && !stats.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function stripQuotes(value) {
+  if (typeof value !== 'string') return value;
+  if (value.length < 2) return value.trim();
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+    return value.slice(1, -1).trim();
+  }
+  if (first === '"' || first === "'") {
+    return value.slice(1).trim();
+  }
+  if (last === '"' || last === "'") {
+    return value.slice(0, -1).trim();
+  }
+  return value.trim();
+}
+
+function parseInlineList(raw) {
+  if (typeof raw !== 'string') return [];
+  const value = raw.trim();
+  if (!value.startsWith('[') || !value.endsWith(']')) return [];
+  const inner = value.slice(1, -1).trim();
+  if (!inner) return [];
+  return inner
+    .split(',')
+    .map(item => stripQuotes(item.trim()))
+    .filter(Boolean);
+}
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseFrontmatter(content) {
+  const sanitized = content.replace(/^\uFEFF/, '');
+  const lines = sanitized.split(/\r?\n/);
+  if (!lines.length || lines[0].trim() !== '---') {
+    return { data: {}, body: content, errors: [], hasFrontmatter: false };
+  }
+
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      endIndex = i;
+      break;
+    }
+  }
+
+  if (endIndex === -1) {
+    return {
+      data: {},
+      body: content,
+      errors: ['Missing closing frontmatter delimiter (---).'],
+      hasFrontmatter: true,
+    };
+  }
+
+  const errors = [];
+  const fmText = lines.slice(1, endIndex).join('\n');
+  let data = {};
+
+  try {
+    const doc = yaml.parseDocument(fmText, { prettyErrors: false });
+    if (doc.errors && doc.errors.length) {
+      errors.push(...doc.errors.map(error => error.message));
+    }
+    data = doc.toJS();
+  } catch (err) {
+    errors.push(err.message);
+    data = {};
+  }
+
+  if (!isPlainObject(data)) {
+    errors.push('Frontmatter must be a YAML mapping/object.');
+    data = {};
+  }
+
+  const body = lines.slice(endIndex + 1).join('\n');
+  return { data, body, errors, hasFrontmatter: true };
+}
+
+function tokenize(value) {
+  if (!value) return [];
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .split(' ')
+    .map(token => token.trim())
+    .filter(Boolean);
+}
+
+function unique(list) {
+  const seen = new Set();
+  const result = [];
+  for (const item of list) {
+    if (!item || seen.has(item)) continue;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+
+function readSkill(skillDir, skillId) {
+  const skillPath = path.join(skillDir, skillId, 'SKILL.md');
+  const content = fs.readFileSync(skillPath, 'utf8');
+  const { data } = parseFrontmatter(content);
+  const name = typeof data.name === 'string' && data.name.trim()
+    ? data.name.trim()
+    : skillId;
+  const description = typeof data.description === 'string'
+    ? data.description.trim()
+    : '';
+
+  let tags = [];
+  if (Array.isArray(data.tags)) {
+    tags = data.tags.map(tag => String(tag).trim());
+  } else if (typeof data.tags === 'string' && data.tags.trim()) {
+    const inlineTags = parseInlineList(data.tags);
+    const parts = inlineTags.length > 0
+      ? inlineTags
+      : (data.tags.includes(',') ? data.tags.split(',') : data.tags.split(/\s+/));
+    tags = parts.map(tag => tag.trim());
+  } else if (isPlainObject(data.metadata) && data.metadata.tags) {
+    const rawTags = data.metadata.tags;
+    if (Array.isArray(rawTags)) {
+      tags = rawTags.map(tag => String(tag).trim());
+    } else if (typeof rawTags === 'string' && rawTags.trim()) {
+      const inlineTags = parseInlineList(rawTags);
+      const parts = inlineTags.length > 0
+        ? inlineTags
+        : (rawTags.includes(',') ? rawTags.split(',') : rawTags.split(/\s+/));
+      tags = parts.map(tag => tag.trim());
+    }
+  }
+
+  tags = tags.filter(Boolean);
+  const category = typeof data.category === 'string' ? data.category.trim() : '';
+  const risk = typeof data.risk === 'string' ? data.risk.trim() : '';
+
+  return {
+    id: skillId,
+    name,
+    description,
+    category,
+    risk,
+    tags,
+    path: skillPath,
+    content,
+  };
+}
+
+function listSkillIds(skillsDir) {
+  return fs.readdirSync(skillsDir)
+    .filter(entry => {
+      if (entry.startsWith('.')) return false;
+      const dirPath = path.join(skillsDir, entry);
+      if (!isSafeDirectory(dirPath)) return false;
+      const skillPath = path.join(dirPath, 'SKILL.md');
+      return isSafeSkillFile(skillPath);
+    })
+    .sort();
+}
+
+/**
+ * Recursively list all skill directory paths under skillsDir (relative paths).
+ * Matches generate_index.py behavior so catalog includes nested skills (e.g. game-development/2d-games).
+ */
+function listSkillIdsRecursive(skillsDir, baseDir = skillsDir, acc = []) {
+  const stack = [baseDir];
+  const visited = new Set();
+
+  while (stack.length > 0) {
+    const currentDir = stack.pop();
+    const resolvedDir = path.resolve(currentDir);
+    if (visited.has(resolvedDir)) continue;
+    visited.add(resolvedDir);
+
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const dirPath = path.join(currentDir, entry.name);
+      if (!isSafeDirectory(dirPath)) continue;
+
+      const skillPath = path.join(dirPath, 'SKILL.md');
+      const relPath = path.relative(skillsDir, dirPath).split(path.sep).join('/');
+      if (isSafeSkillFile(skillPath)) {
+        acc.push(relPath);
+      }
+      stack.push(dirPath);
+    }
+  }
+  return acc.sort();
+}
+
+module.exports = {
+  listSkillIds,
+  listSkillIdsRecursive,
+  parseFrontmatter,
+  parseInlineList,
+  readSkill,
+  stripQuotes,
+  tokenize,
+  unique,
+};

package/tools/lib/symlink-safety.js

@@ -0,0 +1,27 @@
+const fs = require("fs");
+const path = require("path");
+
+function isPathInside(basePath, candidatePath) {
+  const base = fs.existsSync(basePath) ? getRealPath(basePath) : path.resolve(basePath);
+  const candidate = path.resolve(candidatePath);
+  const relative = path.relative(base, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function getRealPath(targetPath) {
+  if (typeof fs.realpathSync.native === "function") {
+    return fs.realpathSync.native(targetPath);
+  }
+  return fs.realpathSync(targetPath);
+}
+
+function resolveSafeRealPath(rootPath, targetPath) {
+  const realPath = getRealPath(targetPath);
+  return isPathInside(rootPath, realPath) ? realPath : null;
+}
+
+module.exports = {
+  getRealPath,
+  isPathInside,
+  resolveSafeRealPath,
+};

package/tools/lib/workflow-contract.js

@@ -0,0 +1,197 @@
+const fs = require("fs");
+const path = require("path");
+
+const { findProjectRoot } = require("./project-root");
+
+const DOC_PREFIXES = ["docs/"];
+const DOC_FILES = new Set(["README.md", "CONTRIBUTING.md", "CHANGELOG.md", "walkthrough.md"]);
+const INFRA_PREFIXES = [".github/", "tools/", "apps/"];
+const INFRA_FILES = new Set(["package.json", "package-lock.json"]);
+const REFERENCES_PREFIXES = ["docs/", ".github/", "tools/", "apps/", "data/"];
+const REFERENCES_FILES = new Set([
+  "README.md",
+  "CONTRIBUTING.md",
+  "CHANGELOG.md",
+  "walkthrough.md",
+  "package.json",
+  "package-lock.json",
+]);
+
+function normalizeRepoPath(filePath) {
+  return String(filePath || "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function matchesContractEntry(filePath, entry) {
+  const normalizedPath = normalizeRepoPath(filePath);
+  const normalizedEntry = normalizeRepoPath(entry);
+
+  if (!normalizedEntry) {
+    return false;
+  }
+
+  if (normalizedEntry.endsWith("/")) {
+    return normalizedPath.startsWith(normalizedEntry);
+  }
+
+  return normalizedPath === normalizedEntry;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function loadWorkflowContract(startDir = __dirname) {
+  const projectRoot = findProjectRoot(startDir);
+  const configPath = path.join(projectRoot, "tools", "config", "generated-files.json");
+  const rawConfig = fs.readFileSync(configPath, "utf8");
+  const config = JSON.parse(rawConfig);
+
+  return {
+    projectRoot,
+    configPath,
+    derivedFiles: config.derivedFiles.map(normalizeRepoPath),
+    mixedFiles: config.mixedFiles.map(normalizeRepoPath),
+    releaseManagedFiles: config.releaseManagedFiles.map(normalizeRepoPath),
+  };
+}
+
+function getManagedFiles(contract, options = {}) {
+  const includeMixed = Boolean(options.includeMixed);
+  const includeReleaseManaged = Boolean(options.includeReleaseManaged);
+  const managedFiles = [...contract.derivedFiles];
+
+  if (includeMixed) {
+    managedFiles.push(...contract.mixedFiles);
+  }
+
+  if (includeReleaseManaged) {
+    managedFiles.push(...contract.releaseManagedFiles);
+  }
+
+  return [...new Set(managedFiles.map(normalizeRepoPath))];
+}
+
+function isDerivedFile(filePath, contract) {
+  return contract.derivedFiles.some((entry) => matchesContractEntry(filePath, entry));
+}
+
+function isMixedFile(filePath, contract) {
+  return contract.mixedFiles.some((entry) => matchesContractEntry(filePath, entry));
+}
+
+function isDocLikeFile(filePath) {
+  const normalized = normalizeRepoPath(filePath);
+  return normalized.endsWith(".md") || DOC_FILES.has(normalized) || DOC_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+function isInfraLikeFile(filePath) {
+  const normalized = normalizeRepoPath(filePath);
+  return (
+    INFRA_FILES.has(normalized) ||
+    INFRA_PREFIXES.some((prefix) => normalized.startsWith(prefix))
+  );
+}
+
+function classifyChangedFiles(changedFiles, contract) {
+  const categories = new Set();
+  const normalizedFiles = changedFiles.map(normalizeRepoPath).filter(Boolean);
+
+  for (const filePath of normalizedFiles) {
+    if (isDerivedFile(filePath, contract)) {
+      continue;
+    }
+
+    const isSkillPath = filePath.startsWith("skills/");
+
+    if (isSkillPath) {
+      categories.add("skill");
+    }
+
+    if (!isSkillPath && (isDocLikeFile(filePath) || isMixedFile(filePath, contract))) {
+      categories.add("docs");
+    }
+
+    if (isInfraLikeFile(filePath)) {
+      categories.add("infra");
+    }
+  }
+
+  const orderedCategories = ["skill", "docs", "infra"].filter((category) => categories.has(category));
+  let primaryCategory = "none";
+  if (orderedCategories.includes("infra")) {
+    primaryCategory = "infra";
+  } else if (orderedCategories.includes("skill")) {
+    primaryCategory = "skill";
+  } else if (orderedCategories.includes("docs")) {
+    primaryCategory = "docs";
+  }
+
+  return {
+    categories: orderedCategories,
+    primaryCategory,
+  };
+}
+
+function getDirectDerivedChanges(changedFiles, contract) {
+  return changedFiles
+    .map(normalizeRepoPath)
+    .filter(Boolean)
+    .filter((filePath) => isDerivedFile(filePath, contract));
+}
+
+function requiresReferencesValidation(changedFiles, contract) {
+  return changedFiles
+    .map(normalizeRepoPath)
+    .filter(Boolean)
+    .some((filePath) => {
+      if (isDerivedFile(filePath, contract) || isMixedFile(filePath, contract)) {
+        return true;
+      }
+
+      return (
+        REFERENCES_FILES.has(filePath) ||
+        REFERENCES_PREFIXES.some((prefix) => filePath.startsWith(prefix))
+      );
+    });
+}
+
+function extractChangelogSection(content, version) {
+  const headingExpression = new RegExp(`^## \\[${escapeRegExp(version)}\\].*$`, "m");
+  const headingMatch = headingExpression.exec(content);
+  if (!headingMatch) {
+    throw new Error(`CHANGELOG.md does not contain a section for version ${version}.`);
+  }
+
+  const startIndex = headingMatch.index;
+  const remainder = content.slice(startIndex + headingMatch[0].length);
+  const nextSectionRelativeIndex = remainder.search(/^## \[/m);
+  const endIndex =
+    nextSectionRelativeIndex === -1
+      ? content.length
+      : startIndex + headingMatch[0].length + nextSectionRelativeIndex;
+
+  return `${content.slice(startIndex, endIndex).trim()}\n`;
+}
+
+function hasQualityChecklist(body) {
+  return /quality bar checklist/i.test(String(body || ""));
+}
+
+function hasIssueLink(body) {
+  return /(?:closes|fixes)\s+#\d+/i.test(String(body || ""));
+}
+
+module.exports = {
+  classifyChangedFiles,
+  extractChangelogSection,
+  getDirectDerivedChanges,
+  getManagedFiles,
+  hasIssueLink,
+  hasQualityChecklist,
+  isDerivedFile,
+  isMixedFile,
+  loadWorkflowContract,
+  normalizeRepoPath,
+  matchesContractEntry,
+  requiresReferencesValidation,
+};