install-agent-skill 1.0.0

package/bin/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Install Agent Skill v1.0.0
+ */
+import { c, step, fatal, intro, outro } from "./lib/ui.js";
+import { command, params, flags, VERSION } from "./lib/config.js";
+
+// --- MAIN ---
+async function main() {
+    intro(c.bgBlue(c.white(` Install Agent Skill v${VERSION} `)));
+
+    // Basic command routing
+    let cmdModule;
+
+    try {
+        switch (command) {
+            case "list":
+            case "ls":
+            case "init":
+                cmdModule = await import("./lib/commands/init.js");
+                await cmdModule.run();
+                break;
+            case "install":
+            case "add":
+            case "i":
+                cmdModule = await import("./lib/commands/install.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "uninstall":
+            case "remove":
+            case "rm":
+                cmdModule = await import("./lib/commands/uninstall.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "update":
+                cmdModule = await import("./lib/commands/update.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "lock":
+                cmdModule = await import("./lib/commands/lock.js");
+                await cmdModule.run();
+                break;
+            case "verify":
+                cmdModule = await import("./lib/commands/verify.js");
+                await cmdModule.run();
+                break;
+            case "doctor":
+                cmdModule = await import("./lib/commands/doctor.js");
+                await cmdModule.run();
+                break;
+            case "cache":
+                cmdModule = await import("./lib/commands/cache.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "validate":
+            case "check":
+                cmdModule = await import("./lib/commands/validate.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "analyze":
+                cmdModule = await import("./lib/commands/analyze.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "info":
+            case "show":
+                cmdModule = await import("./lib/commands/info.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "help":
+            case "--help":
+            case "-h":
+                cmdModule = await import("./lib/commands/help.js");
+                await cmdModule.run();
+                break;
+            case "--version":
+            case "-V":
+                console.log(VERSION);
+                break;
+            default:
+                // Handle direct install via org/repo syntax
+                if (command.includes("/")) {
+                    cmdModule = await import("./lib/commands/install.js");
+                    await cmdModule.run(command);
+                } else {
+                    console.log(`Unknown command: ${command}`);
+                    cmdModule = await import("./lib/commands/help.js");
+                    await cmdModule.run();
+                }
+        }
+    } catch (err) {
+        console.error(c.red("\nError: " + err.message));
+        if (process.env.DEBUG) console.error(err.stack);
+        process.exit(1);
+    }
+}
+
+main().catch(err => {
+    console.error(c.red("\nFatal Error: " + err.message));
+    process.exit(1);
+});

package/bin/lib/commands/analyze.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Analyze command - Skill structure analysis
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, getDirSize } from "../helpers.js";
+import { parseSkillMdFrontmatter, detectSkillStructure } from "../skills.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+
+/**
+ * Analyze skill structure
+ * @param {string} skillName - Skill to analyze
+ */
+export async function run(skillName) {
+    if (!skillName) fatal("Missing skill name");
+
+    const scope = resolveScope();
+    const skillDir = path.join(scope, skillName);
+
+    if (!fs.existsSync(skillDir)) fatal(`Skill not found: ${skillName}`);
+
+    stepLine();
+    step(c.bold(`Skill Analysis: ${skillName}`), S.diamondFilled, "cyan");
+    console.log(`${c.gray(S.branch)}  ${c.dim("Path: " + skillDir)}`);
+    stepLine();
+
+    // SKILL.md frontmatter
+    const smp = path.join(skillDir, "SKILL.md");
+    if (fs.existsSync(smp)) {
+        const m = parseSkillMdFrontmatter(smp);
+        console.log(`${c.gray(S.branch)}  ${c.cyan("SKILL.md Frontmatter:")}`);
+        console.log(`${c.gray(S.branch)}    Name: ${m.name || c.dim("(not set)")}`);
+        console.log(`${c.gray(S.branch)}    Description: ${m.description ? m.description.substring(0, 60) : c.red("(MISSING)")}`);
+        if (m.tags) console.log(`${c.gray(S.branch)}    Tags: ${m.tags.join(", ")}`);
+        stepLine();
+    }
+
+    // Structure
+    const structure = detectSkillStructure(skillDir);
+    console.log(`${c.gray(S.branch)}  ${c.cyan("Structure:")}`);
+
+    const items = [
+        ["resources", structure.hasResources],
+        ["examples", structure.hasExamples],
+        ["scripts", structure.hasScripts],
+        ["constitution", structure.hasConstitution],
+        ["doctrines", structure.hasDoctrines]
+    ];
+
+    items.forEach(([n, has]) => {
+        console.log(`${c.gray(S.branch)}    ${has ? c.green(S.check) : c.dim("○")} ${has ? c.bold(n) : c.dim(n)}`);
+    });
+
+    stepLine();
+
+    // Antigravity Score
+    let score = 0;
+    if (fs.existsSync(smp)) score += 20;
+    const m = parseSkillMdFrontmatter(smp);
+    if (m.description) score += 25;
+    if (m.tags && m.tags.length > 0) score += 10;
+    if (structure.hasResources || structure.hasExamples || structure.hasScripts) score += 20;
+    if (fs.existsSync(path.join(skillDir, ".skill-source.json"))) score += 10;
+    if (structure.hasConstitution || structure.hasDoctrines) score += 15;
+
+    const scoreColor = score >= 80 ? c.green : score >= 50 ? c.yellow : c.red;
+    console.log(`${c.gray(S.branch)}  ${c.cyan("Antigravity Score:")} ${scoreColor(score + "/100")}`);
+    stepLine();
+}

package/bin/lib/commands/cache.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Cache command
+ */
+
+import fs from "fs";
+import { step, stepLine, S, c, fatal, success } from "../ui.js";
+import { getDirSize, formatBytes, listBackups } from "../helpers.js";
+import { CACHE_ROOT, REGISTRY_CACHE, BACKUP_DIR, DRY } from "../config.js";
+
+/**
+ * Manage cache
+ * @param {string} [sub] - Subcommand: info, clear, backups
+ */
+export async function run(sub) {
+    stepLine();
+
+    if (sub === "clear") {
+        if (DRY) {
+            step(`Would clear: ${CACHE_ROOT}`, S.diamond);
+            return;
+        }
+        if (fs.existsSync(CACHE_ROOT)) {
+            const size = getDirSize(CACHE_ROOT);
+            fs.rmSync(CACHE_ROOT, { recursive: true, force: true });
+            success(`Cache cleared (${formatBytes(size)})`);
+        } else {
+            step("Cache already empty", S.diamond);
+        }
+        return;
+    }
+
+    if (sub === "info" || !sub) {
+        if (!fs.existsSync(CACHE_ROOT)) {
+            step("Cache is empty", S.diamond);
+            return;
+        }
+
+        const rs = fs.existsSync(REGISTRY_CACHE) ? getDirSize(REGISTRY_CACHE) : 0;
+        const bs = fs.existsSync(BACKUP_DIR) ? getDirSize(BACKUP_DIR) : 0;
+
+        step(c.bold("Cache Info"), S.diamondFilled, "cyan");
+        console.log(`${c.gray(S.branch)}  Location: ${CACHE_ROOT}`);
+        console.log(`${c.gray(S.branch)}  Registries: ${formatBytes(rs)}`);
+        console.log(`${c.gray(S.branch)}  Backups: ${formatBytes(bs)}`);
+        console.log(`${c.gray(S.branch)}  Total: ${formatBytes(getDirSize(CACHE_ROOT))}`);
+        stepLine();
+        return;
+    }
+
+    if (sub === "backups") {
+        const backups = listBackups();
+        if (backups.length === 0) {
+            step("No backups found", S.diamond);
+            return;
+        }
+
+        step(c.bold("Backups"), S.diamondFilled, "cyan");
+        stepLine();
+        backups.forEach(b => console.log(`${c.gray(S.branch)}  ${b.name} (${formatBytes(b.size)})`));
+        stepLine();
+        return;
+    }
+
+    fatal(`Unknown cache subcommand: ${sub}`);
+}

package/bin/lib/commands/doctor.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Doctor command - Health check
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, merkleHash, loadSkillLock } from "../helpers.js";
+import { step, stepLine, S, c } from "../ui.js";
+import { STRICT, FIX, DRY, cwd } from "../config.js";
+
+/**
+ * Run health check on installed skills
+ */
+export async function run() {
+    const scope = resolveScope();
+
+    if (!fs.existsSync(scope)) {
+        stepLine();
+        step("No skills directory found", S.diamond);
+        return;
+    }
+
+    stepLine();
+    step(c.bold("Health Check"), S.diamondFilled, "cyan");
+    stepLine();
+
+    let errors = 0, warnings = 0;
+    const lock = fs.existsSync(path.join(cwd, ".agent", "skill-lock.json")) ? loadSkillLock() : null;
+
+    for (const name of fs.readdirSync(scope)) {
+        const dir = path.join(scope, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+
+        // Check SKILL.md
+        if (!fs.existsSync(path.join(dir, "SKILL.md"))) {
+            step(`${name}: ${c.red("missing SKILL.md")}`, S.cross, "red");
+            errors++;
+            continue;
+        }
+
+        // Check metadata
+        const mf = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(mf)) {
+            step(`${name}: ${c.red("missing metadata")}`, S.cross, "red");
+            errors++;
+            continue;
+        }
+
+        const m = JSON.parse(fs.readFileSync(mf, "utf-8"));
+        const actual = merkleHash(dir);
+
+        // Check checksum
+        if (actual !== m.checksum) {
+            if (FIX && !DRY) {
+                m.checksum = actual;
+                fs.writeFileSync(mf, JSON.stringify(m, null, 2));
+                step(`${name}: ${c.yellow("checksum fixed")}`, S.diamond, "yellow");
+            } else {
+                step(`${name}: ${c.yellow("checksum drift")}`, S.diamond, "yellow");
+                STRICT ? errors++ : warnings++;
+            }
+        } else if (lock && !lock.skills[name]) {
+            step(`${name}: ${c.yellow("not in lock")}`, S.diamond, "yellow");
+            STRICT ? errors++ : warnings++;
+        } else {
+            step(`${name}: ${c.green("healthy")}`, S.check, "green");
+        }
+    }
+
+    stepLine();
+    console.log(`${c.gray(S.branch)}  Errors: ${errors}, Warnings: ${warnings}`);
+    stepLine();
+
+    if (STRICT && errors) process.exit(1);
+}

package/bin/lib/commands/help.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Help command
+ */
+
+import { c } from "../ui.js";
+import { VERSION } from "../config.js";
+
+/**
+ * Show help
+ */
+export async function run() {
+    console.log(`
+  ${c.bold("add-skill")} ${c.dim("v" + VERSION)}
+
+  ${c.bold("Usage")}
+    $ add-skill <command> [options]
+
+  ${c.bold("Commands")}
+    <org/repo>          Install all skills from repository
+    <org/repo#skill>    Install specific skill
+    list                List installed skills
+    uninstall <skill>   Remove a skill
+    update <skill>      Update a skill
+    verify              Verify checksums
+    doctor              Check health
+    lock                Generate skill-lock.json
+    init                Initialize skills directory
+    validate [skill]    Validate against Antigravity spec
+    analyze <skill>     Analyze skill structure
+    cache [info|clear]  Manage cache
+    info <skill>        Show skill info
+
+  ${c.bold("Options")}
+    --global, -g        Use global scope
+    --force, -f         Force operation
+    --strict            Fail on violations
+    --fix               Auto-fix issues
+    --dry-run           Preview only
+    --verbose, -v       Detailed output
+    --json              JSON output
+`);
+}

package/bin/lib/commands/info.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Info command
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, formatDate } from "../helpers.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+
+/**
+ * Show skill info
+ * @param {string} name
+ */
+export async function run(name) {
+    if (!name) fatal("Missing skill name");
+
+    const scope = resolveScope();
+    const localDir = path.join(scope, name);
+
+    stepLine();
+
+    if (fs.existsSync(localDir)) {
+        step(`${c.bold(name)} ${c.green("(installed)")}`, S.diamondFilled, "cyan");
+        console.log(`${c.gray(S.branch)}  ${c.dim("Path: " + localDir)}`);
+
+        const mf = path.join(localDir, ".skill-source.json");
+        if (fs.existsSync(mf)) {
+            const m = JSON.parse(fs.readFileSync(mf, "utf-8"));
+            console.log(`${c.gray(S.branch)}  Repo: ${m.repo || "local"}`);
+            console.log(`${c.gray(S.branch)}  Installed: ${formatDate(m.installedAt)}`);
+        }
+        stepLine();
+        return;
+    }
+
+    step(`Skill not installed: ${name}`, S.diamond, "yellow");
+    stepLine();
+}

package/bin/lib/commands/init.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Init command
+ */
+
+import fs from "fs";
+import { step, stepLine, S, success } from "../ui.js";
+import { GLOBAL, GLOBAL_DIR, WORKSPACE, DRY, cwd } from "../config.js";
+import path from "path";
+
+/**
+ * Initialize skills directory
+ */
+export async function run() {
+    stepLine();
+
+    const targetDir = GLOBAL ? GLOBAL_DIR : WORKSPACE;
+
+    if (fs.existsSync(targetDir)) {
+        step(`Skills directory already exists: ${targetDir}`, S.check, "green");
+        return;
+    }
+
+    if (DRY) {
+        step(`Would create: ${targetDir}`, S.diamond);
+        return;
+    }
+
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    // Create .gitignore if workspace
+    if (!GLOBAL) {
+        const gi = path.join(cwd, ".agent", ".gitignore");
+        if (!fs.existsSync(gi)) {
+            fs.writeFileSync(gi, "# Skill caches\nskills/*/.skill-source.json\n");
+        }
+    }
+
+    success(`Initialized: ${targetDir}`);
+}