@agentskillkit/agent-skills 3.2.2 → 3.2.5

package/packages/kit/lib/helpers.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Utility helper functions
+ */
+
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { BACKUP_DIR, DRY, cwd, GLOBAL, WORKSPACE, GLOBAL_DIR, REGISTRIES_FILE } from "./config.js";
+
+/**
+ * Get directory size recursively
+ * @param {string} dir - Directory path
+ * @returns {number} Size in bytes
+ */
+export function getDirSize(dir) {
+    let size = 0;
+    try {
+        const walk = (p) => {
+            for (const f of fs.readdirSync(p)) {
+                const full = path.join(p, f);
+                const stat = fs.statSync(full);
+                if (stat.isDirectory()) walk(full);
+                else size += stat.size;
+            }
+        };
+        walk(dir);
+    } catch (err) {
+        // Directory may not exist or be inaccessible
+        if (process.env.DEBUG) console.error(`getDirSize error: ${err.message}`);
+    }
+    return size;
+}
+
+/**
+ * Format bytes to human readable
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KB";
+    return (bytes / 1024 / 1024).toFixed(1) + " MB";
+}
+
+/**
+ * Format ISO date string
+ * @param {string} [iso]
+ * @returns {string}
+ */
+export function formatDate(iso) {
+    return iso ? new Date(iso).toLocaleDateString() : "unknown";
+}
+
+/**
+ * Calculate merkle hash of directory
+ * @param {string} dir - Directory path
+ * @returns {string} SHA256 hash
+ */
+export function merkleHash(dir) {
+    const files = [];
+    const walk = (p) => {
+        for (const f of fs.readdirSync(p)) {
+            if (f === ".skill-source.json") continue;
+            const full = path.join(p, f);
+            const stat = fs.statSync(full);
+            if (stat.isDirectory()) walk(full);
+            else {
+                const h = crypto.createHash("sha256").update(fs.readFileSync(full)).digest("hex");
+                files.push(`${path.relative(dir, full)}:${h}`);
+            }
+        }
+    };
+    walk(dir);
+    files.sort();
+    return crypto.createHash("sha256").update(files.join("|")).digest("hex");
+}
+
+/**
+ * Parse skill spec string
+ * @param {string} spec - Spec like org/repo#skill@ref
+ * @returns {import('./types.js').ParsedSpec}
+ */
+export function parseSkillSpec(spec) {
+    if (!spec || typeof spec !== 'string') {
+        throw new Error('Skill spec is required');
+    }
+
+    const [repoPart, skillPart] = spec.split("#");
+
+    if (!repoPart.includes('/')) {
+        throw new Error(`Invalid spec format: "${spec}". Expected: org/repo or org/repo#skill`);
+    }
+
+    const [org, repo] = repoPart.split("/");
+
+    if (!org || !repo) {
+        throw new Error(`Invalid spec: missing org or repo in "${spec}"`);
+    }
+
+    const [skill, ref] = (skillPart || "").split("@");
+    return { org, repo, skill: skill || undefined, ref: ref || undefined };
+}
+
+/**
+ * Resolve scope based on flags and cwd
+ * @returns {string} Skills directory path
+ */
+export function resolveScope() {
+    if (GLOBAL) return GLOBAL_DIR;
+    if (fs.existsSync(path.join(cwd, ".agent"))) return WORKSPACE;
+    return GLOBAL_DIR;
+}
+
+/**
+ * Create backup of skill directory
+ * @param {string} skillDir - Source directory
+ * @param {string} skillName - Skill name for backup naming
+ * @returns {string|null} Backup path or null if dry run
+ */
+export function createBackup(skillDir, skillName) {
+    if (DRY) return null;
+
+    try {
+        const ts = new Date().toISOString().replace(/[:.]/g, "-");
+        const bp = path.join(BACKUP_DIR, `${skillName}_${ts}`);
+        fs.mkdirSync(BACKUP_DIR, { recursive: true });
+
+        // Resolve symlink to real path (Windows compatibility)
+        const realPath = fs.realpathSync(skillDir);
+
+        fs.cpSync(realPath, bp, { recursive: true });
+        return bp;
+    } catch (err) {
+        // Fallback: try direct copy if realpath fails
+        try {
+            const ts = new Date().toISOString().replace(/[:.]/g, "-");
+            const bp = path.join(BACKUP_DIR, `${skillName}_${ts}`);
+            fs.cpSync(skillDir, bp, { recursive: true });
+            return bp;
+        } catch (fallbackErr) {
+            if (process.env.DEBUG) {
+                console.error(`Backup failed for ${skillName}:`, fallbackErr.message);
+            }
+            return null;
+        }
+    }
+}
+
+/**
+ * List backups for a skill
+ * @param {string} [skillName] - Filter by skill name
+ * @returns {import('./types.js').Backup[]}
+ */
+export function listBackups(skillName = null) {
+    if (!fs.existsSync(BACKUP_DIR)) return [];
+    const backups = [];
+    for (const name of fs.readdirSync(BACKUP_DIR)) {
+        if (skillName && !name.startsWith(skillName + "_")) continue;
+        const bp = path.join(BACKUP_DIR, name);
+        backups.push({ name, path: bp, createdAt: fs.statSync(bp).mtime, size: getDirSize(bp) });
+    }
+    return backups.sort((a, b) => b.createdAt - a.createdAt);
+}
+
+/**
+ * Load skill lock file
+ * @returns {import('./types.js').SkillLock}
+ */
+export function loadSkillLock() {
+    const f = path.join(cwd, ".agent", "skill-lock.json");
+    if (!fs.existsSync(f)) throw new Error("skill-lock.json not found");
+    return JSON.parse(fs.readFileSync(f, "utf-8"));
+}
+
+/**
+ * Load registries list
+ * @returns {string[]}
+ */
+export function loadRegistries() {
+    try {
+        return fs.existsSync(REGISTRIES_FILE) ? JSON.parse(fs.readFileSync(REGISTRIES_FILE, "utf-8")) : [];
+    } catch (err) {
+        if (process.env.DEBUG) console.error(`loadRegistries error: ${err.message}`);
+        return [];
+    }
+}
+
+/**
+ * Save registries list
+ * @param {string[]} regs
+ */
+export function saveRegistries(regs) {
+    fs.mkdirSync(path.dirname(REGISTRIES_FILE), { recursive: true });
+    fs.writeFileSync(REGISTRIES_FILE, JSON.stringify(regs, null, 2));
+}
+

package/packages/kit/lib/helpers.test.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Tests for helpers.js
+ */
+import { describe, it, expect } from "vitest";
+import { formatBytes, formatDate, parseSkillSpec } from "./helpers.js";
+
+describe("formatBytes", () => {
+    it("formats bytes correctly", () => {
+        expect(formatBytes(0)).toBe("0 B");
+        expect(formatBytes(512)).toBe("512 B");
+        expect(formatBytes(1024)).toBe("1.0 KB");
+        expect(formatBytes(1536)).toBe("1.5 KB");
+        expect(formatBytes(1048576)).toBe("1.0 MB");
+        expect(formatBytes(1572864)).toBe("1.5 MB");
+    });
+});
+
+describe("formatDate", () => {
+    it("returns 'unknown' for undefined", () => {
+        expect(formatDate()).toBe("unknown");
+        expect(formatDate(undefined)).toBe("unknown");
+    });
+
+    it("formats ISO date strings", () => {
+        const result = formatDate("2026-01-25T00:00:00.000Z");
+        expect(result).toBeTruthy();
+        expect(typeof result).toBe("string");
+    });
+});
+
+describe("parseSkillSpec", () => {
+    it("parses org/repo format", () => {
+        const result = parseSkillSpec("agentskillkit/agent-skills");
+        expect(result.org).toBe("agentskillkit");
+        expect(result.repo).toBe("agent-skills");
+        expect(result.skill).toBeUndefined();
+        expect(result.ref).toBeUndefined();
+    });
+
+    it("parses org/repo#skill format", () => {
+        const result = parseSkillSpec("agentskillkit/agent-skills#react-patterns");
+        expect(result.org).toBe("agentskillkit");
+        expect(result.repo).toBe("agent-skills");
+        expect(result.skill).toBe("react-patterns");
+    });
+
+    it("parses org/repo#skill@ref format", () => {
+        const result = parseSkillSpec("agentskillkit/agent-skills#react-patterns@v1.0.0");
+        expect(result.org).toBe("agentskillkit");
+        expect(result.repo).toBe("agent-skills");
+        expect(result.skill).toBe("react-patterns");
+        expect(result.ref).toBe("v1.0.0");
+    });
+
+    it("throws error for invalid spec", () => {
+        expect(() => parseSkillSpec("")).toThrow("Skill spec is required");
+        expect(() => parseSkillSpec("invalid")).toThrow("Invalid spec format");
+        expect(() => parseSkillSpec(null)).toThrow("Skill spec is required");
+    });
+});

package/packages/kit/lib/installer.js

@@ -0,0 +1,164 @@
+import fs from "fs";
+import path from "path";
+import { homedir } from "os";
+import { GLOBAL_DIR } from "./config.js";
+import { merkleHash } from "./helpers.js";
+import { AGENTS } from "./agents.js";
+
+const home = homedir();
+
+/**
+ * Install a skill to the destination using the specified method.
+ * @param {string} src - Source directory (temp)
+ * @param {string} dest - Destination directory (project)
+ * @param {string} method - 'symlink' or 'copy'
+ * @param {Object} metadata - Metadata for .skill-source.json
+ */
+export async function installSkill(src, dest, method, metadata) {
+    if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+
+    if (method === "symlink") {
+        // For symlink: Move to global persistent storage first
+        // Storage path: ~/.gemini/antigravity/skills/storage/<org>/<repo>/<skill>
+        // Metadata must contain org, repo, skill
+        const { repo: repoStr, skill } = metadata;
+        const [org, repo] = repoStr.split("/");
+
+        const storageBase = path.join(GLOBAL_DIR, "storage", org, repo, skill);
+
+        // Ensure fresh copy in storage
+        if (fs.existsSync(storageBase)) fs.rmSync(storageBase, { recursive: true, force: true });
+        fs.mkdirSync(path.dirname(storageBase), { recursive: true });
+
+        // Copy from tmp to storage
+        await fs.promises.cp(src, storageBase, { recursive: true });
+
+        // Create junction
+        fs.symlinkSync(storageBase, dest, "junction");
+    } else {
+        // Copy directly
+        await fs.promises.cp(src, dest, { recursive: true });
+    }
+
+    // Write metadata
+    const hash = merkleHash(dest);
+    const metaFile = path.join(dest, ".skill-source.json");
+
+    fs.writeFileSync(metaFile, JSON.stringify({
+        ...metadata,
+        checksum: hash,
+        installedAt: new Date().toISOString(),
+        method: method
+    }, null, 2));
+}
+
+/**
+ * Install a skill to multiple agents
+ * @param {string} src - Source directory containing the skill
+ * @param {string} skillName - Name of the skill
+ * @param {Array<{name: string, displayName: string, skillsDir: string, globalSkillsDir: string}>} agents - Agents to install to
+ * @param {Object} options - Installation options
+ * @param {string} options.method - 'symlink' or 'copy'
+ * @param {string} options.scope - 'project' or 'global'
+ * @param {Object} options.metadata - Metadata for tracking
+ * @returns {Promise<{success: Array, failed: Array}>}
+ */
+export async function installSkillForAgents(src, skillName, agents, options = {}) {
+    const { method = "symlink", scope = "project", metadata = {} } = options;
+    const results = { success: [], failed: [] };
+
+    // For symlink mode: first copy to canonical location
+    let canonicalPath = null;
+
+    if (method === "symlink") {
+        // Canonical: .agents/skills/<skill-name> or ~/.agents/skills/<skill-name>
+        const baseDir = scope === "global" ? home : process.cwd();
+        canonicalPath = path.join(baseDir, ".agents", "skills", skillName);
+
+        // Ensure fresh copy in canonical
+        if (fs.existsSync(canonicalPath)) {
+            fs.rmSync(canonicalPath, { recursive: true, force: true });
+        }
+        fs.mkdirSync(path.dirname(canonicalPath), { recursive: true });
+
+        try {
+            await fs.promises.cp(src, canonicalPath, { recursive: true });
+
+            // Write metadata to canonical location
+            const hash = merkleHash(canonicalPath);
+            const metaFile = path.join(canonicalPath, ".skill-source.json");
+            fs.writeFileSync(metaFile, JSON.stringify({
+                ...metadata,
+                skillName,
+                checksum: hash,
+                installedAt: new Date().toISOString(),
+                method: method,
+                scope: scope,
+                agents: agents.map(a => a.name)
+            }, null, 2));
+        } catch (err) {
+            // If canonical copy fails, abort
+            return {
+                success: [],
+                failed: agents.map(a => ({ agent: a.displayName, error: `Canonical copy failed: ${err.message}` }))
+            };
+        }
+    }
+
+    // Install to each agent
+    for (const agent of agents) {
+        const agentConfig = AGENTS[agent.name];
+        if (!agentConfig) {
+            results.failed.push({ agent: agent.displayName, error: "Unknown agent" });
+            continue;
+        }
+
+        // Determine destination path
+        const baseDir = scope === "global" ? agentConfig.globalSkillsDir : path.join(process.cwd(), agentConfig.skillsDir);
+        const destPath = path.join(baseDir, skillName);
+
+        try {
+            // Ensure parent directory exists
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+            // Remove existing if any
+            if (fs.existsSync(destPath)) {
+                fs.rmSync(destPath, { recursive: true, force: true });
+            }
+
+            if (method === "symlink" && canonicalPath) {
+                // Create symlink to canonical location
+                try {
+                    fs.symlinkSync(canonicalPath, destPath, "junction");
+                    results.success.push({ agent: agent.displayName, path: destPath, mode: "symlink" });
+                } catch (symlinkErr) {
+                    // Fallback to copy if symlink fails (Windows permissions)
+                    await fs.promises.cp(canonicalPath, destPath, { recursive: true });
+                    results.success.push({ agent: agent.displayName, path: destPath, mode: "copy (symlink failed)" });
+                }
+            } else {
+                // Direct copy
+                await fs.promises.cp(src, destPath, { recursive: true });
+
+                // Write metadata
+                const hash = merkleHash(destPath);
+                const metaFile = path.join(destPath, ".skill-source.json");
+                fs.writeFileSync(metaFile, JSON.stringify({
+                    ...metadata,
+                    skillName,
+                    checksum: hash,
+                    installedAt: new Date().toISOString(),
+                    method: "copy",
+                    scope: scope
+                }, null, 2));
+
+                results.success.push({ agent: agent.displayName, path: destPath, mode: "copy" });
+            }
+        } catch (err) {
+            results.failed.push({ agent: agent.displayName, error: err.message });
+        }
+    }
+
+    return results;
+}
+

package/packages/kit/lib/skills.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Skill detection and parsing
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope } from "./helpers.js";
+import { getDirSize } from "./helpers.js";
+
+/**
+ * Parse SKILL.md YAML frontmatter
+ * @param {string} p - Path to SKILL.md
+ * @returns {import('./types.js').SkillMeta}
+ */
+export function parseSkillMdFrontmatter(p) {
+    try {
+        const content = fs.readFileSync(p, "utf-8");
+        const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!match) return {};
+
+        /** @type {import('./types.js').SkillMeta} */
+        const meta = {};
+
+        for (const line of match[1].split(/\r?\n/)) {
+            const i = line.indexOf(":");
+            if (i === -1) continue;
+            const key = line.substring(0, i).trim();
+            const val = line.substring(i + 1).trim();
+            if (key === "tags") meta.tags = val.split(",").map(t => t.trim()).filter(Boolean);
+            else if (key && val) meta[key] = val;
+        }
+        return meta;
+    } catch (err) {
+        if (process.env.DEBUG) console.error(`parseSkillMdFrontmatter error: ${err.message}`);
+        return {};
+    }
+}
+
+/**
+ * Detect skill directory structure
+ * @param {string} dir - Skill directory
+ * @returns {import('./types.js').SkillStructure}
+ */
+export function detectSkillStructure(dir) {
+    /** @type {import('./types.js').SkillStructure} */
+    const s = {
+        hasResources: false,
+        hasExamples: false,
+        hasScripts: false,
+        hasConstitution: false,
+        hasDoctrines: false,
+        hasEnforcement: false,
+        hasProposals: false,
+        directories: [],
+        files: []
+    };
+
+    try {
+        for (const item of fs.readdirSync(dir)) {
+            const full = path.join(dir, item);
+            if (fs.statSync(full).isDirectory()) {
+                s.directories.push(item);
+                const l = item.toLowerCase();
+                if (l === "resources") s.hasResources = true;
+                if (l === "examples") s.hasExamples = true;
+                if (l === "scripts") s.hasScripts = true;
+                if (l === "constitution") s.hasConstitution = true;
+                if (l === "doctrines") s.hasDoctrines = true;
+                if (l === "enforcement") s.hasEnforcement = true;
+                if (l === "proposals") s.hasProposals = true;
+            } else {
+                s.files.push(item);
+            }
+        }
+    } catch (err) {
+        if (process.env.DEBUG) console.error(`detectSkillStructure error: ${err.message}`);
+    }
+    return s;
+}
+
+/**
+ * Get all installed skills
+ * @returns {import('./types.js').Skill[]}
+ */
+export function getInstalledSkills() {
+    const scope = resolveScope();
+    /** @type {import('./types.js').Skill[]} */
+    const skills = [];
+
+    if (!fs.existsSync(scope)) return skills;
+
+    for (const name of fs.readdirSync(scope)) {
+        const dir = path.join(scope, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+
+        const metaFile = path.join(dir, ".skill-source.json");
+        const skillFile = path.join(dir, "SKILL.md");
+
+        if (fs.existsSync(metaFile) || fs.existsSync(skillFile)) {
+            const meta = fs.existsSync(metaFile) ? JSON.parse(fs.readFileSync(metaFile, "utf-8")) : {};
+            const hasSkillMd = fs.existsSync(skillFile);
+            const skillMeta = hasSkillMd ? parseSkillMdFrontmatter(skillFile) : {};
+
+            skills.push({
+                name,
+                path: dir,
+                ...meta,
+                hasSkillMd,
+                description: skillMeta.description || meta.description || "",
+                tags: skillMeta.tags || [],
+                author: skillMeta.author || meta.publisher || "",
+                version: skillMeta.version || meta.ref || "unknown",
+                structure: detectSkillStructure(dir),
+                size: getDirSize(dir)
+            });
+        }
+    }
+    return skills;
+}

package/packages/kit/lib/skills.test.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Tests for skills.js
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { parseSkillMdFrontmatter, detectSkillStructure } from "./skills.js";
+
+describe("parseSkillMdFrontmatter", () => {
+    let tempDir;
+    let skillMdPath;
+
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-test-"));
+        skillMdPath = path.join(tempDir, "SKILL.md");
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it("parses valid frontmatter", () => {
+        const content = `---
+name: test-skill
+description: A test skill for testing
+version: 1.0.0
+author: Test Author
+tags: react, testing, patterns
+---
+
+# Test Skill
+
+Some content here.
+`;
+        fs.writeFileSync(skillMdPath, content);
+
+        const result = parseSkillMdFrontmatter(skillMdPath);
+
+        expect(result.name).toBe("test-skill");
+        expect(result.description).toBe("A test skill for testing");
+        expect(result.version).toBe("1.0.0");
+        expect(result.author).toBe("Test Author");
+        expect(result.tags).toEqual(["react", "testing", "patterns"]);
+    });
+
+    it("returns empty object for no frontmatter", () => {
+        fs.writeFileSync(skillMdPath, "# Just a heading\n\nNo frontmatter here.");
+
+        const result = parseSkillMdFrontmatter(skillMdPath);
+
+        expect(result).toEqual({});
+    });
+
+    it("returns empty object for non-existent file", () => {
+        const result = parseSkillMdFrontmatter("/non/existent/path/SKILL.md");
+        expect(result).toEqual({});
+    });
+});
+
+describe("detectSkillStructure", () => {
+    let tempDir;
+
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-structure-"));
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it("detects standard directories", () => {
+        fs.mkdirSync(path.join(tempDir, "resources"));
+        fs.mkdirSync(path.join(tempDir, "examples"));
+        fs.mkdirSync(path.join(tempDir, "scripts"));
+        fs.writeFileSync(path.join(tempDir, "SKILL.md"), "# Skill");
+
+        const result = detectSkillStructure(tempDir);
+
+        expect(result.hasResources).toBe(true);
+        expect(result.hasExamples).toBe(true);
+        expect(result.hasScripts).toBe(true);
+        expect(result.directories).toContain("resources");
+        expect(result.directories).toContain("examples");
+        expect(result.directories).toContain("scripts");
+        expect(result.files).toContain("SKILL.md");
+    });
+
+    it("detects governance directories", () => {
+        fs.mkdirSync(path.join(tempDir, "constitution"));
+        fs.mkdirSync(path.join(tempDir, "doctrines"));
+        fs.mkdirSync(path.join(tempDir, "enforcement"));
+        fs.mkdirSync(path.join(tempDir, "proposals"));
+
+        const result = detectSkillStructure(tempDir);
+
+        expect(result.hasConstitution).toBe(true);
+        expect(result.hasDoctrines).toBe(true);
+        expect(result.hasEnforcement).toBe(true);
+        expect(result.hasProposals).toBe(true);
+    });
+
+    it("returns empty structure for non-existent dir", () => {
+        const result = detectSkillStructure("/non/existent/path");
+
+        expect(result.directories).toEqual([]);
+        expect(result.files).toEqual([]);
+    });
+});