@hasna/skills 0.0.2

package/src/lib/skillinfo.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  getSkillDocs,
+  getSkillBestDoc,
+  getSkillRequirements,
+  generateEnvExample,
+  generateSkillMd,
+} from "./skillinfo";
+import { installSkill } from "./installer";
+
+let testDir: string;
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), "skillinfo-test-"));
+});
+
+afterEach(() => {
+  const { rmSync } = require("fs");
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe("skillinfo", () => {
+  describe("getSkillDocs", () => {
+    test("returns docs for skill with SKILL.md", () => {
+      const docs = getSkillDocs("image");
+      expect(docs).not.toBeNull();
+      expect(docs!.skillMd).toBeTruthy();
+      expect(docs!.skillMd).toContain("Image Generation");
+    });
+
+    test("returns docs for skill with CLAUDE.md only", () => {
+      const docs = getSkillDocs("deep-research");
+      expect(docs).not.toBeNull();
+      expect(docs!.claudeMd).toBeTruthy();
+    });
+
+    test("returns null for nonexistent skill", () => {
+      const docs = getSkillDocs("nonexistent-xyz");
+      expect(docs).toBeNull();
+    });
+
+    test("returns null fields for missing doc files", () => {
+      const docs = getSkillDocs("scaffold-project");
+      expect(docs).not.toBeNull();
+      // At least one doc exists
+      const hasAny = docs!.skillMd || docs!.readme || docs!.claudeMd;
+      // scaffold-project has CLAUDE.md at minimum
+      expect(docs!.claudeMd).toBeTruthy();
+    });
+  });
+
+  describe("getSkillBestDoc", () => {
+    test("returns SKILL.md when available", () => {
+      const doc = getSkillBestDoc("image");
+      expect(doc).toBeTruthy();
+      expect(doc).toContain("Image Generation");
+    });
+
+    test("falls back to CLAUDE.md", () => {
+      const doc = getSkillBestDoc("deep-research");
+      expect(doc).toBeTruthy();
+    });
+
+    test("returns null for nonexistent skill", () => {
+      const doc = getSkillBestDoc("nonexistent-xyz");
+      expect(doc).toBeNull();
+    });
+  });
+
+  describe("getSkillRequirements", () => {
+    test("extracts env vars from image skill", () => {
+      const reqs = getSkillRequirements("image");
+      expect(reqs).not.toBeNull();
+      expect(reqs!.envVars).toContain("OPENAI_API_KEY");
+      expect(reqs!.envVars).toContain("GEMINI_API_KEY");
+    });
+
+    test("extracts CLI command from package.json", () => {
+      const reqs = getSkillRequirements("image");
+      expect(reqs).not.toBeNull();
+      expect(reqs!.cliCommand).toBe("skill-image");
+    });
+
+    test("extracts CLI command for deep-research", () => {
+      const reqs = getSkillRequirements("deep-research");
+      expect(reqs).not.toBeNull();
+      expect(reqs!.cliCommand).toBe("skill-deep-research");
+    });
+
+    test("returns null for nonexistent skill", () => {
+      const reqs = getSkillRequirements("nonexistent-xyz");
+      expect(reqs).toBeNull();
+    });
+
+    test("returns sorted env vars", () => {
+      const reqs = getSkillRequirements("image");
+      expect(reqs).not.toBeNull();
+      const vars = reqs!.envVars;
+      const sorted = [...vars].sort();
+      expect(vars).toEqual(sorted);
+    });
+
+    test("extracts dependencies from package.json", () => {
+      const reqs = getSkillRequirements("deep-research");
+      expect(reqs).not.toBeNull();
+      expect(reqs!.dependencies).toHaveProperty("commander");
+    });
+  });
+
+  describe("generateEnvExample", () => {
+    test("returns empty string when no skills installed", () => {
+      const result = generateEnvExample(testDir);
+      expect(result).toBe("");
+    });
+
+    test("returns empty string when .skills dir does not exist", () => {
+      const result = generateEnvExample(join(testDir, "nonexistent"));
+      expect(result).toBe("");
+    });
+
+    test("generates env example from installed skills", () => {
+      installSkill("image", { targetDir: testDir });
+      const result = generateEnvExample(testDir);
+      expect(result).toContain("OPENAI_API_KEY");
+      expect(result).toContain("GEMINI_API_KEY");
+      expect(result).toContain("# Used by: image");
+    });
+
+    test("includes header comments", () => {
+      installSkill("image", { targetDir: testDir });
+      const result = generateEnvExample(testDir);
+      expect(result).toContain("# Environment variables for installed skills");
+      expect(result).toContain("# Auto-generated by: skills init");
+    });
+
+    test("groups by provider prefix", () => {
+      installSkill("image", { targetDir: testDir });
+      const result = generateEnvExample(testDir);
+      expect(result).toContain("# OPENAI");
+      expect(result).toContain("# GEMINI");
+    });
+  });
+
+  describe("generateSkillMd", () => {
+    test("generates SKILL.md for a skill without one", () => {
+      const md = generateSkillMd("deep-research");
+      expect(md).not.toBeNull();
+      expect(md!).toContain("---");
+      expect(md!).toContain("name: deep-research");
+      expect(md!).toContain("description:");
+      expect(md!).toContain("Deep Research");
+    });
+
+    test("generates SKILL.md for a skill with existing SKILL.md source", () => {
+      // image has a SKILL.md, but generateSkillMd still works
+      const md = generateSkillMd("image");
+      expect(md).not.toBeNull();
+      expect(md!).toContain("name: image");
+    });
+
+    test("includes category and tags", () => {
+      const md = generateSkillMd("deep-research");
+      expect(md).not.toBeNull();
+      expect(md!).toContain("Category: Research & Writing");
+      expect(md!).toContain("Tags:");
+    });
+
+    test("includes CLI section for skills with bin entry", () => {
+      const md = generateSkillMd("deep-research");
+      expect(md).not.toBeNull();
+      expect(md!).toContain("## CLI");
+      expect(md!).toContain("skills run deep-research");
+    });
+
+    test("returns null for nonexistent skill", () => {
+      const md = generateSkillMd("nonexistent-xyz");
+      expect(md).toBeNull();
+    });
+
+    test("has valid YAML frontmatter", () => {
+      const md = generateSkillMd("deep-research");
+      expect(md).not.toBeNull();
+      // Check frontmatter structure
+      const parts = md!.split("---");
+      expect(parts.length).toBeGreaterThanOrEqual(3);
+      // Frontmatter is between first and second ---
+      const frontmatter = parts[1];
+      expect(frontmatter).toContain("name:");
+      expect(frontmatter).toContain("description:");
+    });
+  });
+});

package/src/lib/skillinfo.ts

@@ -0,0 +1,356 @@
+/**
+ * Skill info - reads docs, requirements, and metadata from skill source
+ */
+
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { getSkillPath } from "./installer.js";
+import { getSkill } from "./registry.js";
+
+export interface SkillDocs {
+  skillMd: string | null;
+  readme: string | null;
+  claudeMd: string | null;
+}
+
+export interface SkillRequirements {
+  envVars: string[];
+  systemDeps: string[];
+  cliCommand: string | null;
+  dependencies: Record<string, string>;
+}
+
+/**
+ * Read documentation files from a skill
+ */
+export function getSkillDocs(name: string): SkillDocs | null {
+  const skillPath = getSkillPath(name);
+  if (!existsSync(skillPath)) return null;
+
+  return {
+    skillMd: readIfExists(join(skillPath, "SKILL.md")),
+    readme: readIfExists(join(skillPath, "README.md")),
+    claudeMd: readIfExists(join(skillPath, "CLAUDE.md")),
+  };
+}
+
+/**
+ * Get the best available documentation for a skill (SKILL.md > README.md > CLAUDE.md)
+ */
+export function getSkillBestDoc(name: string): string | null {
+  const docs = getSkillDocs(name);
+  if (!docs) return null;
+  return docs.skillMd || docs.readme || docs.claudeMd || null;
+}
+
+/**
+ * Extract requirements from a skill's source files
+ */
+export function getSkillRequirements(name: string): SkillRequirements | null {
+  const skillPath = getSkillPath(name);
+  if (!existsSync(skillPath)) return null;
+
+  // Read all text content to scan
+  const texts: string[] = [];
+  for (const file of ["SKILL.md", "README.md", "CLAUDE.md", ".env.example", ".env.local.example"]) {
+    const content = readIfExists(join(skillPath, file));
+    if (content) texts.push(content);
+  }
+  const allText = texts.join("\n");
+
+  // Extract env vars
+  const envVarPattern = /\b([A-Z][A-Z0-9_]{2,}(?:_API_KEY|_KEY|_TOKEN|_SECRET|_URL|_ID|_PASSWORD|_ENDPOINT|_REGION|_BUCKET))\b/g;
+  const genericEnvPattern = /\b((?:OPENAI|ANTHROPIC|GEMINI|XAI|ELEVENLABS|DEEPGRAM|REPLICATE|FAL|STABILITY|EXA|FIRECRAWL|TWILIO|SENDGRID|RESEND|SLACK|DISCORD|NOTION|LINEAR|GITHUB|AWS|GOOGLE|CLOUDFLARE|VERCEL|SUPABASE|STRIPE)_[A-Z_]+)\b/g;
+  const envVars = new Set<string>();
+  for (const pattern of [envVarPattern, genericEnvPattern]) {
+    let match;
+    while ((match = pattern.exec(allText)) !== null) {
+      envVars.add(match[1]);
+    }
+  }
+
+  // Extract system deps
+  const systemDeps = new Set<string>();
+  const depPatterns: [RegExp, string][] = [
+    [/\bffmpeg\b/i, "ffmpeg"],
+    [/\bplaywright\b/i, "playwright"],
+    [/\bchromium\b/i, "chromium"],
+    [/\bpuppeteer\b/i, "puppeteer"],
+    [/\bpython3?\b/i, "python"],
+    [/\bdocker\b/i, "docker"],
+    [/\bpandoc\b/i, "pandoc"],
+    [/\bimageMagick\b|imagemagick|\bconvert\b.*image/i, "imagemagick"],
+    [/\bwkhtmltopdf\b/i, "wkhtmltopdf"],
+    [/\bgit\b(?! ?(hub|lab|ignore))/i, "git"],
+  ];
+  for (const [pattern, dep] of depPatterns) {
+    if (pattern.test(allText)) {
+      systemDeps.add(dep);
+    }
+  }
+
+  // Read CLI command from package.json
+  let cliCommand: string | null = null;
+  let dependencies: Record<string, string> = {};
+  const pkgPath = join(skillPath, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.bin) {
+        const binKeys = Object.keys(pkg.bin);
+        if (binKeys.length > 0) cliCommand = binKeys[0];
+      }
+      dependencies = pkg.dependencies || {};
+    } catch {}
+  }
+
+  return {
+    envVars: Array.from(envVars).sort(),
+    systemDeps: Array.from(systemDeps).sort(),
+    cliCommand,
+    dependencies,
+  };
+}
+
+/**
+ * Run a skill by name with given arguments
+ */
+export async function runSkill(
+  name: string,
+  args: string[],
+  options: { installed?: boolean } = {}
+): Promise<{ exitCode: number; error?: string }> {
+  // Look in .skills/ first (installed), then fall back to package skills/
+  const skillName = name.startsWith("skill-") ? name : `skill-${name}`;
+  let skillPath: string;
+
+  if (options.installed) {
+    skillPath = join(process.cwd(), ".skills", skillName);
+  } else {
+    // Check installed first
+    const installedPath = join(process.cwd(), ".skills", skillName);
+    if (existsSync(installedPath)) {
+      skillPath = installedPath;
+    } else {
+      skillPath = getSkillPath(name);
+    }
+  }
+
+  if (!existsSync(skillPath)) {
+    return { exitCode: 1, error: `Skill '${name}' not found` };
+  }
+
+  // Read package.json for bin entry
+  const pkgPath = join(skillPath, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { exitCode: 1, error: `No package.json in skill '${name}'` };
+  }
+
+  let entryPoint: string;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    if (pkg.bin) {
+      const binValues = Object.values(pkg.bin) as string[];
+      entryPoint = binValues[0];
+    } else if (pkg.scripts?.dev) {
+      // Parse "bun run bin/cli.ts" -> "bin/cli.ts"
+      const devScript = pkg.scripts.dev as string;
+      const match = devScript.match(/(?:bun\s+run\s+)(.+)/);
+      entryPoint = match ? match[1] : "bin/cli.ts";
+    } else {
+      entryPoint = "bin/cli.ts";
+    }
+  } catch {
+    return { exitCode: 1, error: `Failed to parse package.json for skill '${name}'` };
+  }
+
+  const entryPath = join(skillPath, entryPoint);
+  if (!existsSync(entryPath)) {
+    return { exitCode: 1, error: `Entry point '${entryPoint}' not found in skill '${name}'` };
+  }
+
+  // Install deps if node_modules missing
+  const nodeModules = join(skillPath, "node_modules");
+  if (!existsSync(nodeModules)) {
+    const install = Bun.spawn(["bun", "install", "--no-save"], {
+      cwd: skillPath,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await install.exited;
+  }
+
+  // Run the skill
+  const proc = Bun.spawn(["bun", "run", entryPath, ...args], {
+    cwd: skillPath,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+  });
+
+  const exitCode = await proc.exited;
+  return { exitCode };
+}
+
+/**
+ * Generate a .env.example from installed skills
+ */
+export function generateEnvExample(targetDir: string = process.cwd()): string {
+  const skillsDir = join(targetDir, ".skills");
+  if (!existsSync(skillsDir)) return "";
+
+  const dirs = readdirSync(skillsDir).filter(
+    (f) => f.startsWith("skill-") && existsSync(join(skillsDir, f, "package.json"))
+  );
+
+  const envMap = new Map<string, string[]>();
+
+  for (const dir of dirs) {
+    const skillName = dir.replace("skill-", "");
+    const skillPath = join(skillsDir, dir);
+
+    const texts: string[] = [];
+    for (const file of ["SKILL.md", "README.md", "CLAUDE.md", ".env.example"]) {
+      const content = readIfExists(join(skillPath, file));
+      if (content) texts.push(content);
+    }
+    const allText = texts.join("\n");
+
+    const envVarPattern = /\b([A-Z][A-Z0-9_]{2,}(?:_API_KEY|_KEY|_TOKEN|_SECRET|_URL|_ID|_PASSWORD|_ENDPOINT|_REGION|_BUCKET))\b/g;
+    const genericEnvPattern = /\b((?:OPENAI|ANTHROPIC|GEMINI|XAI|ELEVENLABS|DEEPGRAM|REPLICATE|FAL|STABILITY|EXA|FIRECRAWL|TWILIO|SENDGRID|RESEND|SLACK|DISCORD|NOTION|LINEAR|GITHUB|AWS|GOOGLE|CLOUDFLARE|VERCEL|SUPABASE|STRIPE)_[A-Z_]+)\b/g;
+
+    for (const pattern of [envVarPattern, genericEnvPattern]) {
+      let match;
+      while ((match = pattern.exec(allText)) !== null) {
+        const envVar = match[1];
+        if (!envMap.has(envVar)) {
+          envMap.set(envVar, []);
+        }
+        if (!envMap.get(envVar)!.includes(skillName)) {
+          envMap.get(envVar)!.push(skillName);
+        }
+      }
+    }
+  }
+
+  if (envMap.size === 0) return "";
+
+  const lines = [
+    "# Environment variables for installed skills",
+    "# Auto-generated by: skills init",
+    "",
+  ];
+
+  // Group by provider prefix
+  const sorted = Array.from(envMap.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+  let lastPrefix = "";
+  for (const [envVar, skills] of sorted) {
+    const prefix = envVar.split("_")[0];
+    if (prefix !== lastPrefix) {
+      if (lastPrefix) lines.push("");
+      lines.push(`# ${prefix}`);
+      lastPrefix = prefix;
+    }
+    lines.push(`# Used by: ${skills.join(", ")}`);
+    lines.push(`${envVar}=`);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Generate a SKILL.md for a skill that doesn't have one.
+ * Builds from registry metadata, README.md/CLAUDE.md content, and package.json info.
+ */
+export function generateSkillMd(name: string): string | null {
+  const meta = getSkill(name);
+  if (!meta) return null;
+
+  const skillPath = getSkillPath(name);
+  if (!existsSync(skillPath)) return null;
+
+  // Build frontmatter
+  const frontmatter = [
+    "---",
+    `name: ${meta.name}`,
+    `description: ${meta.description}`,
+    "---",
+  ].join("\n");
+
+  // Try to extract useful content from existing docs
+  const readme = readIfExists(join(skillPath, "README.md"));
+  const claudeMd = readIfExists(join(skillPath, "CLAUDE.md"));
+
+  // Get CLI command from package.json
+  let cliCommand: string | null = null;
+  const pkgPath = join(skillPath, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.bin) {
+        const binKeys = Object.keys(pkg.bin);
+        if (binKeys.length > 0) cliCommand = binKeys[0];
+      }
+    } catch {}
+  }
+
+  // Build body from available sources
+  const sections: string[] = [];
+  sections.push(`# ${meta.displayName}`);
+  sections.push("");
+  sections.push(meta.description);
+
+  // Extract content from README (skip title if it duplicates)
+  if (readme) {
+    const lines = readme.split("\n");
+    // Skip first heading if it matches the display name
+    let startIdx = 0;
+    if (lines[0]?.startsWith("# ")) {
+      startIdx = 1;
+      // Skip blank line after title
+      if (lines[1]?.trim() === "") startIdx = 2;
+    }
+    const body = lines.slice(startIdx).join("\n").trim();
+    if (body) {
+      sections.push("");
+      sections.push(body);
+    }
+  } else if (claudeMd) {
+    const lines = claudeMd.split("\n");
+    let startIdx = 0;
+    if (lines[0]?.startsWith("# ")) {
+      startIdx = 1;
+      if (lines[1]?.trim() === "") startIdx = 2;
+    }
+    const body = lines.slice(startIdx).join("\n").trim();
+    if (body) {
+      sections.push("");
+      sections.push(body);
+    }
+  }
+
+  if (cliCommand) {
+    sections.push("");
+    sections.push("## CLI");
+    sections.push("");
+    sections.push("```bash");
+    sections.push(`skills run ${meta.name}`);
+    sections.push("```");
+  }
+
+  sections.push("");
+  sections.push(`Category: ${meta.category}`);
+  sections.push(`Tags: ${meta.tags.join(", ")}`);
+
+  return frontmatter + "\n\n" + sections.join("\n") + "\n";
+}
+
+function readIfExists(path: string): string | null {
+  try {
+    if (existsSync(path)) {
+      return readFileSync(path, "utf-8");
+    }
+  } catch {}
+  return null;
+}