@framers/agentos-skills-registry 0.2.0 → 0.2.1

package/scripts/update-registry.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * Regenerate skills registry.json from SKILL.md files.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.join(__dirname, '..');
+const registryPath = path.join(packageRoot, 'registry.json');
+const curatedRoot = path.join(packageRoot, 'registry', 'curated');
+const communityRoot = path.join(packageRoot, 'registry', 'community');
+
+function readFrontmatter(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  try {
+    const parsed = YAML.parse(match[1]);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function listSkillDirs(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(root, d.name, 'SKILL.md')))
+    .map((d) => d.name)
+    .sort();
+}
+
+function cleanObject(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v === undefined) continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    if (v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+function toStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === 'string' && v.trim().length > 0);
+}
+
+function slugToDisplayName(slug) {
+  return slug
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function buildEntry(name, source, updatedAt) {
+  const skillPath = path.join(packageRoot, 'registry', source, name, 'SKILL.md');
+  const fm = readFrontmatter(skillPath);
+  const metadata = fm?.metadata?.agentos && typeof fm.metadata.agentos === 'object'
+    ? fm.metadata.agentos
+    : undefined;
+
+  return cleanObject({
+    id: source === 'curated' ? `com.framers.skill.${name}` : `com.community.skill.${name}`,
+    name,
+    displayName:
+      typeof fm.name === 'string' && fm.name.trim().length > 0
+        ? fm.name
+        : slugToDisplayName(name),
+    version: typeof fm.version === 'string' && fm.version ? fm.version : '1.0.0',
+    path: `registry/${source}/${name}`,
+    description: typeof fm.description === 'string' ? fm.description : '',
+    category: typeof fm.category === 'string' && fm.category ? fm.category : 'uncategorized',
+    namespace: typeof fm.namespace === 'string' && fm.namespace ? fm.namespace : 'wunderland',
+    verified: source === 'curated',
+    source,
+    verifiedAt: source === 'curated' ? updatedAt : undefined,
+    keywords: toStringArray(fm.tags),
+    requiredSecrets: toStringArray(fm.requires_secrets),
+    requiredTools: toStringArray(fm.requires_tools),
+    metadata: metadata && typeof metadata === 'object' ? metadata : undefined,
+  });
+}
+
+function generateRegistry() {
+  const updated = new Date().toISOString();
+  const curatedNames = listSkillDirs(curatedRoot);
+  const communityNames = listSkillDirs(communityRoot);
+
+  const curated = curatedNames.map((name) => buildEntry(name, 'curated', updated));
+  const community = communityNames.map((name) => buildEntry(name, 'community', updated));
+
+  return {
+    version: '1.0.0',
+    updated,
+    categories: {
+      curated: curatedNames,
+      community: communityNames,
+    },
+    skills: {
+      curated,
+      community,
+    },
+    stats: {
+      totalSkills: curated.length + community.length,
+      curatedCount: curated.length,
+      communityCount: community.length,
+    },
+  };
+}
+
+const registry = generateRegistry();
+fs.writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+
+console.log('✅ Skills registry updated');
+console.log(`   curated: ${registry.stats.curatedCount}`);
+console.log(`   community: ${registry.stats.communityCount}`);
+console.log(`   total: ${registry.stats.totalSkills}`);

package/scripts/validate-skill.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+
+/**
+ * SKILL.md validator for @framers/agentos-skills
+ *
+ * Usage:
+ *   node scripts/validate-skill.mjs registry/community/my-skill/SKILL.md
+ *   node scripts/validate-skill.mjs                                        # validates ALL skills
+ *
+ * Exit code 0 on pass, 1 on fail.
+ * Zero external dependencies — uses only Node.js built-ins.
+ */
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { resolve, basename, dirname, join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const VALID_CATEGORIES = new Set([
+  'information',
+  'developer-tools',
+  'communication',
+  'productivity',
+  'devops',
+  'media',
+  'security',
+  'creative',
+]);
+
+const VALID_NAMESPACES = new Set(['wunderland', 'community']);
+
+const REQUIRED_FIELDS = ['name', 'version', 'description', 'author', 'namespace', 'category', 'tags'];
+
+const MAX_DESCRIPTION_LENGTH = 200;
+
+/** Patterns that suggest accidentally-committed secrets. */
+const SECRET_PATTERNS = [
+  /(?:api[_-]?key|apikey)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i,
+  /(?:secret|token|password|passwd|pwd)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i,
+  /sk-[A-Za-z0-9]{20,}/,                          // OpenAI-style keys
+  /ghp_[A-Za-z0-9]{36,}/,                          // GitHub personal access tokens
+  /gho_[A-Za-z0-9]{36,}/,                          // GitHub OAuth tokens
+  /xox[bpors]-[A-Za-z0-9\-]{10,}/,                 // Slack tokens
+  /AKIA[0-9A-Z]{16}/,                              // AWS access key IDs
+  /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/,       // Private keys
+  /Bearer\s+[A-Za-z0-9_\-\.]{20,}/,                // Bearer tokens
+];
+
+// ---------------------------------------------------------------------------
+// Simple YAML frontmatter parser (no dependencies)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse basic YAML key-value pairs from frontmatter lines.
+ * Handles:
+ *   key: value           -> string
+ *   key: 'value'         -> string (strip quotes)
+ *   key: "value"         -> string (strip quotes)
+ *   key: [a, b, c]       -> string[]
+ *   key: []              -> string[] (empty)
+ *
+ * Nested keys (like metadata.agentos.emoji) are ignored — only top-level
+ * keys matter for required-field validation.
+ */
+function parseSimpleYaml(yamlText) {
+  const result = {};
+  const lines = yamlText.split('\n');
+
+  for (const line of lines) {
+    // Skip blank lines and comments
+    const trimmed = line.trimStart();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Only parse top-level keys (no leading whitespace)
+    if (line[0] === ' ' || line[0] === '\t') continue;
+
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    let value = trimmed.slice(colonIndex + 1).trim();
+
+    if (!key) continue;
+
+    // Inline array: [a, b, c]
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      if (inner === '') {
+        result[key] = [];
+      } else {
+        result[key] = inner.split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, ''));
+      }
+      continue;
+    }
+
+    // Strip surrounding quotes
+    if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a single SKILL.md file. Returns an object with:
+ *   { path, passed, errors[] }
+ */
+function validateSkill(filePath) {
+  const errors = [];
+  const absolutePath = resolve(filePath);
+
+  // --- Read file --------------------------------------------------------
+
+  let content;
+  try {
+    content = readFileSync(absolutePath, 'utf-8');
+  } catch (err) {
+    return { path: absolutePath, passed: false, errors: [`Cannot read file: ${err.message}`] };
+  }
+
+  // --- Split frontmatter / body ----------------------------------------
+
+  const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+  const match = content.match(fmRegex);
+
+  if (!match) {
+    return {
+      path: absolutePath,
+      passed: false,
+      errors: ['File does not contain valid YAML frontmatter (expected --- delimiters).'],
+    };
+  }
+
+  const yamlText = match[1];
+  const markdownBody = match[2];
+
+  // --- Parse YAML -------------------------------------------------------
+
+  const meta = parseSimpleYaml(yamlText);
+
+  // --- Required fields --------------------------------------------------
+
+  for (const field of REQUIRED_FIELDS) {
+    if (meta[field] === undefined || meta[field] === '') {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // --- Category ---------------------------------------------------------
+
+  if (meta.category && !VALID_CATEGORIES.has(meta.category)) {
+    errors.push(
+      `Invalid category "${meta.category}". Must be one of: ${[...VALID_CATEGORIES].join(', ')}`,
+    );
+  }
+
+  // --- Namespace --------------------------------------------------------
+
+  if (meta.namespace && !VALID_NAMESPACES.has(meta.namespace)) {
+    errors.push(
+      `Invalid namespace "${meta.namespace}". Must be one of: ${[...VALID_NAMESPACES].join(', ')}`,
+    );
+  }
+
+  // --- Description length -----------------------------------------------
+
+  if (meta.description && typeof meta.description === 'string' && meta.description.length > MAX_DESCRIPTION_LENGTH) {
+    errors.push(
+      `Description is ${meta.description.length} characters (max ${MAX_DESCRIPTION_LENGTH}).`,
+    );
+  }
+
+  // --- Tags -------------------------------------------------------------
+
+  if (meta.tags !== undefined) {
+    if (!Array.isArray(meta.tags)) {
+      errors.push('tags must be an array.');
+    } else if (meta.tags.length === 0) {
+      errors.push('tags array must contain at least 1 tag.');
+    }
+  }
+
+  // --- Name matches directory -------------------------------------------
+
+  const dirName = basename(dirname(absolutePath));
+  if (meta.name && meta.name !== dirName) {
+    errors.push(
+      `Skill name "${meta.name}" does not match directory name "${dirName}".`,
+    );
+  }
+
+  // --- Markdown body not empty ------------------------------------------
+
+  if (!markdownBody || markdownBody.trim().length === 0) {
+    errors.push('Markdown body is empty. Include usage instructions, Examples, and Constraints.');
+  }
+
+  // --- Secret pattern scan ----------------------------------------------
+
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(content)) {
+      errors.push(`Possible secret or credential detected (pattern: ${pattern.source}). Remove it before submitting.`);
+    }
+  }
+
+  return { path: absolutePath, passed: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Discover all SKILL.md files
+// ---------------------------------------------------------------------------
+
+function discoverSkills(rootDir) {
+  const skills = [];
+  const tiers = ['curated', 'community'];
+
+  for (const tier of tiers) {
+    const tierDir = join(rootDir, 'registry', tier);
+    if (!existsSync(tierDir)) continue;
+
+    for (const entry of readdirSync(tierDir)) {
+      const skillDir = join(tierDir, entry);
+      if (!statSync(skillDir).isDirectory()) continue;
+
+      const skillFile = join(skillDir, 'SKILL.md');
+      if (existsSync(skillFile)) {
+        skills.push(skillFile);
+      }
+    }
+  }
+
+  return skills;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+
+  let filesToValidate;
+
+  if (args.length === 0) {
+    // Validate all skills
+    const rootDir = resolve(dirname(new URL(import.meta.url).pathname), '..');
+    filesToValidate = discoverSkills(rootDir);
+    if (filesToValidate.length === 0) {
+      console.log('No SKILL.md files found in registry/curated/ or registry/community/.');
+      process.exit(0);
+    }
+    console.log(`Validating ${filesToValidate.length} skill(s)...\n`);
+  } else {
+    filesToValidate = [resolve(args[0])];
+  }
+
+  let allPassed = true;
+
+  for (const filePath of filesToValidate) {
+    const result = validateSkill(filePath);
+
+    if (result.passed) {
+      console.log(`  PASS  ${result.path}`);
+    } else {
+      allPassed = false;
+      console.log(`  FAIL  ${result.path}`);
+      for (const err of result.errors) {
+        console.log(`        - ${err}`);
+      }
+    }
+  }
+
+  console.log('');
+
+  if (allPassed) {
+    console.log(`All ${filesToValidate.length} skill(s) passed validation.`);
+    process.exit(0);
+  } else {
+    const failCount = filesToValidate.length - filesToValidate.filter((_, i) => {
+      // Re-validate to count (cheap for small set)
+      return validateSkill(filesToValidate[i]).passed;
+    }).length;
+    // Simpler: just fail
+    console.log('Validation failed. Fix the errors above and re-run.');
+    process.exit(1);
+  }
+}
+
+main();

package/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Type declarations for @framers/agentos-skills-registry catalog.
+ * @module @framers/agentos-skills-registry
+ */
+
+export type SkillInstallKind = "brew" | "apt" | "node" | "go" | "uv" | "download";
+
+export interface SkillInstallSpec {
+  id?: string;
+  kind: SkillInstallKind;
+  label?: string;
+  bins?: string[];
+  os?: readonly string[];
+  formula?: string;
+  package?: string;
+  module?: string;
+  url?: string;
+  archive?: string;
+  extract?: boolean;
+  stripComponents?: number;
+  targetDir?: string;
+}
+
+export interface SkillRequirements {
+  bins?: string[];
+  anyBins?: string[];
+  env?: string[];
+  config?: string[];
+}
+
+export interface SkillMetadata {
+  always?: boolean;
+  skillKey?: string;
+  primaryEnv?: string;
+  emoji?: string;
+  homepage?: string;
+  os?: readonly string[];
+  requires?: SkillRequirements;
+  install?: SkillInstallSpec[];
+}
+
+export interface SkillCatalogEntry {
+  id: string;
+  name: string;
+  version: string;
+  path: string;
+  description: string;
+  verified: boolean;
+  source?: 'curated' | 'community';
+  verifiedAt?: string;
+  keywords?: string[];
+  metadata?: SkillMetadata;
+}
+
+export interface SkillsRegistryStats {
+  totalSkills: number;
+  curatedCount: number;
+  communityCount: number;
+}
+
+export interface SkillsRegistry {
+  version: string;
+  updated: string;
+  categories: {
+    curated: string[];
+    community: string[];
+  };
+  skills: {
+    curated: SkillCatalogEntry[];
+    community: SkillCatalogEntry[];
+  };
+  stats: SkillsRegistryStats;
+}
+
+declare const registry: SkillsRegistry;
+export default registry;
+