install-agent-skill 1.0.0

package/bin/lib/config.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Configuration and argument parsing
+ */
+
+import path from "path";
+import os from "os";
+
+/** Current working directory */
+export const cwd = process.cwd();
+
+/** Local workspace skills directory */
+export const WORKSPACE = path.join(cwd, ".agent", "skills");
+
+/** Global skills directory */
+export const GLOBAL_DIR = path.join(os.homedir(), ".gemini", "antigravity", "skills");
+
+/** Cache root directory */
+export const CACHE_ROOT = process.env.ADD_SKILL_CACHE_DIR || path.join(os.homedir(), ".cache", "add-skill");
+
+/** Registry cache directory */
+export const REGISTRY_CACHE = path.join(CACHE_ROOT, "registries");
+
+/** Registries file path */
+export const REGISTRIES_FILE = path.join(CACHE_ROOT, "registries.json");
+
+/** Backup directory */
+export const BACKUP_DIR = path.join(CACHE_ROOT, "backups");
+
+// --- Argument Parsing ---
+
+const args = process.argv.slice(2);
+
+/** Command name (first non-flag argument) */
+export const command = args[0] || "help";
+
+/** All flags (starting with --) */
+export const flags = new Set(args.filter((a) => a.startsWith("--")));
+
+/** Command parameters (non-flag arguments after command) */
+export const params = args.filter((a) => !a.startsWith("--")).slice(1);
+
+// --- Flag Shortcuts ---
+
+/** Use global scope */
+export const GLOBAL = flags.has("--global") || flags.has("-g");
+
+/** Verbose output */
+export const VERBOSE = flags.has("--verbose") || flags.has("-v");
+
+/** JSON output mode */
+export const JSON_OUTPUT = flags.has("--json");
+
+/** Force operation */
+export const FORCE = flags.has("--force") || flags.has("-f");
+
+/** Dry run mode */
+export const DRY = flags.has("--dry-run");
+
+/** Strict mode */
+export const STRICT = flags.has("--strict");
+
+/** Auto-fix mode */
+export const FIX = flags.has("--fix");
+
+/** Locked mode */
+export const LOCKED = flags.has("--locked");
+
+/** Offline mode */
+export const OFFLINE = flags.has("--offline");
+
+// --- Package Info ---
+
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+
+/** Package version */
+export const VERSION = (() => {
+    try { return require("../../package.json").version; }
+    catch { return "5.0.0"; }
+})();

package/bin/lib/helpers.js

@@ -0,0 +1,155 @@
+/**
+ * @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 { }
+    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) {
+    const [repoPart, skillPart] = spec.split("#");
+    const [org, repo] = repoPart.split("/");
+    const [skill, ref] = (skillPart || "").split("@");
+    return { org, repo, skill, ref };
+}
+
+/**
+ * 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;
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const bp = path.join(BACKUP_DIR, `${skillName}_${ts}`);
+    fs.mkdirSync(BACKUP_DIR, { recursive: true });
+    fs.cpSync(skillDir, bp, { recursive: true });
+    return bp;
+}
+
+/**
+ * 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 { 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/bin/lib/installer.js

@@ -0,0 +1,49 @@
+import fs from "fs";
+import path from "path";
+import { GLOBAL_DIR } from "./config.js";
+import { merkleHash } from "./helpers.js";
+
+/**
+ * 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));
+}

package/bin/lib/skills.js

@@ -0,0 +1,114 @@
+/**
+ * @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 { 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 { }
+    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/bin/lib/types.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview JSDoc Type Definitions for add-skill CLI
+ * Provides IDE autocomplete support
+ */
+
+/**
+ * @typedef {Object} SkillStructure
+ * @property {boolean} hasResources
+ * @property {boolean} hasExamples
+ * @property {boolean} hasScripts
+ * @property {boolean} hasConstitution
+ * @property {boolean} hasDoctrines
+ * @property {boolean} hasEnforcement
+ * @property {boolean} hasProposals
+ * @property {string[]} directories
+ * @property {string[]} files
+ */
+
+/**
+ * @typedef {Object} Skill
+ * @property {string} name - Skill folder name
+ * @property {string} path - Absolute path to skill
+ * @property {boolean} hasSkillMd - Has SKILL.md file
+ * @property {string} description - From SKILL.md frontmatter
+ * @property {string[]} tags - From SKILL.md frontmatter
+ * @property {string} author - Author or publisher
+ * @property {string} version - Version or ref
+ * @property {SkillStructure} structure - Directory structure
+ * @property {number} size - Total size in bytes
+ * @property {string} [repo] - Source repository
+ * @property {string} [skill] - Skill name in repo
+ * @property {string} [ref] - Git ref
+ * @property {string} [checksum] - Merkle hash
+ * @property {string} [installedAt] - ISO timestamp
+ */
+
+/**
+ * @typedef {Object} SkillMeta
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {string} [version]
+ * @property {string} [author]
+ * @property {string[]} [tags]
+ * @property {string} [type]
+ * @property {string} [authority]
+ * @property {string} [parent]
+ */
+
+/**
+ * @typedef {Object} ParsedSpec
+ * @property {string} org - GitHub org
+ * @property {string} repo - GitHub repo
+ * @property {string} [skill] - Skill name
+ * @property {string} [ref] - Git ref
+ */
+
+/**
+ * @typedef {Object} Backup
+ * @property {string} name
+ * @property {string} path
+ * @property {Date} createdAt
+ * @property {number} size
+ */
+
+/**
+ * @typedef {Object} SkillLock
+ * @property {number} lockVersion
+ * @property {string} generatedAt
+ * @property {string} generator
+ * @property {Object.<string, SkillLockEntry>} skills
+ */
+
+/**
+ * @typedef {Object} SkillLockEntry
+ * @property {string} repo
+ * @property {string} skill
+ * @property {string} ref
+ * @property {string} checksum
+ * @property {string} [publisher]
+ */
+
+export { };

package/bin/lib/ui.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview UI components - Install Agent Skill theme
+ */
+
+import kleur from "kleur";
+import { intro, outro, multiselect, select, confirm, isCancel, cancel, text } from "@clack/prompts";
+import ora from "ora";
+
+export { intro, outro, multiselect, select, confirm, isCancel, cancel, text };
+
+/**
+ * Create a spinner
+ */
+export function spinner() {
+    return {
+        _s: null,
+        start(msg) {
+            this._s = ora({
+                text: " " + msg,
+                prefixText: "",
+                color: "blue",
+                spinner: {
+                    interval: 80,
+                    frames: ['◒', '◐', '◓', '◑']
+                }
+            }).start();
+        },
+        stop(msg) {
+            if (this._s) {
+                this._s.stopAndPersist({
+                    symbol: c.cyan(S.diamond),
+                    text: " " + msg
+                });
+            }
+        },
+        fail(msg) {
+            if (this._s) {
+                this._s.stopAndPersist({
+                    symbol: c.red(S.cross),
+                    text: " " + msg
+                });
+            }
+        },
+        message(msg) {
+            if (this._s) this._s.text = " " + msg;
+        }
+    };
+}
+
+// --- Symbols ---
+
+/** UI symbols for tree structure */
+export const S = {
+    branch: "│",
+    diamond: "◇",
+    diamondFilled: "◆",
+    check: "✓",
+    cross: "x",
+    arrow: "→"
+};
+
+// --- Colors ---
+
+/** Color helper functions */
+export const c = {
+    cyan: kleur.cyan,
+    gray: kleur.gray,
+    green: kleur.green,
+    red: kleur.red,
+    yellow: kleur.yellow,
+    magenta: kleur.magenta,
+    blue: kleur.blue,
+    white: kleur.white,
+    bgBlue: kleur.bgBlue,
+    bold: kleur.bold,
+    dim: kleur.dim,
+    inverse: kleur.inverse
+};
+
+// --- UI Functions ---
+
+/**
+ * Print a step in the tree
+ * @param {string} text - Step text
+ * @param {string} [icon] - Icon to use
+ * @param {keyof typeof c} [color] - Color name
+ */
+export function step(text, icon = S.diamond, color = "cyan") {
+    const colorFn = c[color] || c.cyan;
+    console.log(`${colorFn(icon)}  ${text}`);
+}
+
+/**
+ * Print an active step (Blue Filled Diamond)
+ * @param {string} text - Step text
+ */
+export function activeStep(text) {
+    console.log(`${c.blue(S.diamondFilled)}  ${text}`);
+}
+
+/**
+ * Print empty branch line
+ */
+export function stepLine() {
+    console.log(`${c.gray(S.branch)}`);
+}
+
+/**
+ * Print fatal error and exit
+ * @param {string} msg - Error message
+ */
+export function fatal(msg) {
+    console.log(`${c.red(S.cross)}  ${c.red(msg)}`);
+    process.exit(1);
+}
+
+/**
+ * Print success message
+ * @param {string} msg - Success message
+ */
+export function success(msg) {
+    console.log(`${c.cyan(S.diamond)}  ${c.cyan(msg)}`);
+}
+
+/**
+ * Output JSON if JSON_OUTPUT mode
+ * @param {any} data - Data to output
+ * @param {boolean} jsonMode - Whether to output JSON
+ */
+export function outputJSON(data, jsonMode) {
+    if (jsonMode) console.log(JSON.stringify(data, null, 2));
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "install-agent-skill",
+  "version": "1.0.0",
+  "description": "Enterprise-grade Agent Skill Manager with Antigravity Skills support, Progressive Disclosure detection, and semantic routing validation",
+  "license": "MIT",
+  "author": "DataGuruIn <contact@dataguruin.com>",
+  "homepage": "https://github.com/dataguruin/add-skill",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dataguruin/add-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dataguruin/add-skill/issues"
+  },
+  "type": "module",
+  "bin": {
+    "add-skill": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "specs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "skills",
+    "cli",
+    "tooling",
+    "registry",
+    "security",
+    "devops",
+    "automation",
+    "antigravity"
+  ],
+  "scripts": {
+    "lint": "echo \"No lint configured\"",
+    "test": "echo \"No tests yet\"",
+    "ci": "node bin/add-skill.js verify --strict && node bin/add-skill.js doctor --strict"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "boxen": "^8.0.1",
+    "chalk": "^5.4.1",
+    "kleur": "^4.1.5",
+    "ora": "^9.1.0",
+    "prompts": "^2.4.2"
+  }
+}