@poolzin/pool-bot 2026.3.7 → 2026.3.9

package/dist/skills/commands.js

@@ -0,0 +1,351 @@
+/**
+ * CLI commands for skills management
+ * Provides poolbot skills subcommands
+ *
+ * @module skills/commands
+ */
+import { SkillError, } from "./types.js";
+import { getRegistry } from "./registry.js";
+import { getLoader } from "./loader.js";
+import { formatFindings, getSecuritySummary } from "./security.js";
+// ============================================================================
+// Command Registration
+// ============================================================================
+/**
+ * Register skills commands with CLI
+ */
+export function registerSkillsCommands(program) {
+    const mods = program
+        .command("mods")
+        .description("Manage capability modules (SKILL.md files)");
+    // List command
+    mods
+        .command("list")
+        .description("List all available skills")
+        .option("-c, --category <category>", "Filter by category")
+        .option("-t, --tag <tag>", "Filter by tag")
+        .option("-e, --enabled", "Show only enabled skills")
+        .option("--disabled", "Show only disabled skills")
+        .option("-j, --json", "Output as JSON")
+        .action(listCommand);
+    // View command
+    mods
+        .command("view <id>")
+        .description("View skill details")
+        .option("-l, --level <level>", "Disclosure level (metadata|summary|full)", "full")
+        .option("--no-linked", "Skip linked files")
+        .option("--security", "Include security report")
+        .action(viewCommand);
+    // Search command
+    mods
+        .command("search <query>")
+        .description("Search skills by name, description, or tags")
+        .option("-c, --category <category>", "Filter by category")
+        .action(searchCommand);
+    // Enable/disable commands
+    mods
+        .command("enable <id>")
+        .description("Enable a skill")
+        .action(enableCommand);
+    mods
+        .command("disable <id>")
+        .description("Disable a skill")
+        .action(disableCommand);
+    // Scan command
+    mods
+        .command("scan [path]")
+        .description("Scan for skills in directory")
+        .action(scanCommand);
+    // Stats command
+    mods
+        .command("stats")
+        .description("Show skill statistics")
+        .action(statsCommand);
+}
+// ============================================================================
+// Command Implementations
+// ============================================================================
+/**
+ * Ensure registry is initialized with default paths
+ */
+async function ensureRegistry() {
+    const registry = getRegistry({
+        localPaths: ["./skills", "./src/skills"],
+        autoScan: true,
+    });
+    // Auto-scan if empty
+    if (registry.getStats().total === 0) {
+        await registry.scan();
+    }
+    return registry;
+}
+/**
+ * List skills command
+ */
+async function listCommand(options) {
+    const registry = await ensureRegistry();
+    const filters = {};
+    if (options.category)
+        filters.category = options.category;
+    if (options.tag)
+        filters.tags = [options.tag];
+    if (options.enabled)
+        filters.enabledOnly = true;
+    if (options.disabled) {
+        // Invert - show only disabled
+        const all = registry.getAllRefs();
+        const disabled = all.filter((s) => !s.enabled);
+        if (options.json) {
+            console.log(JSON.stringify(disabled, null, 2));
+        }
+        else {
+            printSkillTable(disabled);
+        }
+        return;
+    }
+    const result = registry.search(filters);
+    if (options.json) {
+        console.log(JSON.stringify(result.skills, null, 2));
+    }
+    else {
+        printSkillTable(result.skills);
+        if (result.total > result.skills.length) {
+            console.log(`\nShowing ${result.skills.length} of ${result.total} skills`);
+        }
+    }
+}
+/**
+ * View skill command
+ */
+async function viewCommand(id, options) {
+    const registry = await ensureRegistry();
+    const loader = getLoader();
+    const skill = registry.get(id);
+    if (!skill) {
+        console.error(`Error: Skill '${id}' not found`);
+        process.exit(1);
+    }
+    const level = options.level;
+    // Print header
+    console.log(`\n${"=".repeat(60)}`);
+    console.log(`  ${skill.metadata.name}`);
+    console.log(`  ${skill.metadata.description}`);
+    console.log(`${"=".repeat(60)}\n`);
+    // Print metadata
+    console.log("Metadata:");
+    console.log(`  ID:          ${skill.metadata.id}`);
+    console.log(`  Version:     ${skill.metadata.version}`);
+    console.log(`  Category:    ${skill.metadata.category}`);
+    console.log(`  Author:      ${skill.metadata.author || "Unknown"}`);
+    console.log(`  Tags:        ${skill.metadata.tags.join(", ") || "None"}`);
+    console.log(`  Status:      ${skill.enabled ? "Enabled" : "Disabled"}`);
+    // Print security status
+    const secSummary = skill.securityReport
+        ? getSecuritySummary(skill.securityReport)
+        : { status: "Not scanned", color: "gray", summary: "", counts: {} };
+    console.log(`  Security:    ${secSummary.status}`);
+    // Print content based on level
+    console.log("\n" + "-".repeat(40));
+    if (level === "metadata") {
+        console.log("\n[Metadata only - use --level summary or full for content]");
+        return;
+    }
+    const content = await loader.loadSkill(skill, level);
+    if (content.quickstart) {
+        console.log("\n## Quick Start\n");
+        console.log(content.quickstart);
+    }
+    if (content.usage) {
+        console.log("\n## Usage\n");
+        console.log(content.usage);
+    }
+    if (level === "full") {
+        if (content.examples) {
+            console.log("\n## Examples\n");
+            console.log(content.examples);
+        }
+        if (content.configuration) {
+            console.log("\n## Configuration\n");
+            console.log(content.configuration);
+        }
+        if (content.environment) {
+            console.log("\n## Environment Variables\n");
+            console.log(content.environment);
+        }
+        if (content.api) {
+            console.log("\n## API Reference\n");
+            console.log(content.api);
+        }
+        if (content.troubleshooting) {
+            console.log("\n## Troubleshooting\n");
+            console.log(content.troubleshooting);
+        }
+    }
+    // Print linked files
+    if (options.linked !== false && skill.linkedFiles.length > 0) {
+        console.log("\n## Linked Files\n");
+        for (const file of skill.linkedFiles) {
+            console.log(`  - ${file.path}${file.required ? " (required)" : ""}`);
+            if (options.linked && level === "full") {
+                try {
+                    const loaded = await loader.loadLinkedFile(skill, file.path);
+                    console.log("\n```");
+                    console.log(loaded.content.slice(0, 500));
+                    if (loaded.content.length > 500) {
+                        console.log("\n... [truncated]");
+                    }
+                    console.log("```\n");
+                }
+                catch (error) {
+                    console.log(`  [Error loading: ${error}]`);
+                }
+            }
+        }
+    }
+    // Print security report
+    if (options.security && skill.securityReport) {
+        console.log("\n## Security Report\n");
+        console.log(`Scanner: ${skill.securityReport.scannerVersion}`);
+        console.log(`Scanned: ${skill.securityReport.scannedAt.toISOString()}`);
+        console.log(`Result:  ${getSecuritySummary(skill.securityReport).status}\n`);
+        const findings = formatFindings(skill.securityReport.findings);
+        for (const line of findings) {
+            console.log(line);
+        }
+    }
+}
+/**
+ * Search skills command
+ */
+async function searchCommand(query, options) {
+    const registry = await ensureRegistry();
+    const filters = {
+        query,
+    };
+    if (options.category)
+        filters.category = options.category;
+    const result = registry.search(filters);
+    if (result.skills.length === 0) {
+        console.log(`No skills found matching '${query}'`);
+        return;
+    }
+    console.log(`\nFound ${result.total} skill(s) matching '${query}':\n`);
+    printSkillTable(result.skills);
+}
+/**
+ * Enable skill command
+ */
+async function enableCommand(id) {
+    const registry = await ensureRegistry();
+    try {
+        const success = registry.enable(id);
+        if (success) {
+            console.log(`✓ Skill '${id}' enabled`);
+        }
+        else {
+            console.error(`Error: Skill '${id}' not found`);
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        if (error instanceof SkillError) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+}
+/**
+ * Disable skill command
+ */
+async function disableCommand(id) {
+    const registry = await ensureRegistry();
+    const success = registry.disable(id);
+    if (success) {
+        console.log(`✓ Skill '${id}' disabled`);
+    }
+    else {
+        console.error(`Error: Skill '${id}' not found`);
+        process.exit(1);
+    }
+}
+/**
+ * Scan directory for skills
+ */
+async function scanCommand(path) {
+    const registry = await ensureRegistry();
+    const scanPath = path || "./skills";
+    console.log(`Scanning ${scanPath} for skills...\n`);
+    try {
+        const { loaded, errors } = await registry.scan();
+        console.log(`Loaded ${loaded} skill(s)`);
+        if (errors.length > 0) {
+            console.log(`\n${errors.length} error(s):`);
+            for (const error of errors) {
+                console.log(`  - ${error.message}`);
+            }
+        }
+    }
+    catch (error) {
+        console.error(`Scan failed: ${error}`);
+        process.exit(1);
+    }
+}
+/**
+ * Show skill statistics
+ */
+async function statsCommand() {
+    const registry = await ensureRegistry();
+    const stats = registry.getStats();
+    console.log("\nSkill Statistics");
+    console.log("=".repeat(40));
+    console.log(`\nTotal Skills:    ${stats.total}`);
+    console.log(`Enabled:         ${stats.enabled}`);
+    console.log(`Disabled:        ${stats.disabled}`);
+    console.log("\nBy Category:");
+    for (const [category, count] of Object.entries(stats.byCategory)) {
+        console.log(`  ${category.padEnd(15)} ${count}`);
+    }
+    console.log("\nBy Verification:");
+    for (const [status, count] of Object.entries(stats.byVerification)) {
+        console.log(`  ${status.padEnd(15)} ${count}`);
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Print skills as formatted table
+ */
+function printSkillTable(skills) {
+    if (skills.length === 0) {
+        console.log("No skills found.");
+        return;
+    }
+    // Calculate column widths
+    const idWidth = Math.max(10, ...skills.map((s) => s.id.length));
+    const nameWidth = Math.max(15, ...skills.map((s) => s.name.length));
+    const catWidth = Math.max(10, ...skills.map((s) => s.category.length));
+    const verWidth = 8;
+    // Header
+    console.log(`${"ID".padEnd(idWidth)}  ${"Name".padEnd(nameWidth)}  ${"Category".padEnd(catWidth)}  ${"Version".padEnd(verWidth)}  Status`);
+    console.log("-".repeat(idWidth + nameWidth + catWidth + verWidth + 20));
+    // Rows
+    for (const skill of skills) {
+        const status = skill.enabled ? "✓" : "○";
+        const secIcon = skill.verification === "failed"
+            ? "⚠"
+            : skill.verification === "warning"
+                ? "!"
+                : " ";
+        console.log(`${skill.id.slice(0, idWidth).padEnd(idWidth)}  ` +
+            `${skill.name.slice(0, nameWidth).padEnd(nameWidth)}  ` +
+            `${skill.category.padEnd(catWidth)}  ` +
+            `${skill.version.padEnd(verWidth)}  ` +
+            `${status}${secIcon}`);
+    }
+}
+// ============================================================================
+// Export for testing
+// ============================================================================
+export { listCommand, viewCommand, searchCommand, enableCommand, disableCommand, scanCommand, statsCommand, };

package/dist/skills/index.js

@@ -0,0 +1,167 @@
+/**
+ * PoolBot Skills System
+ *
+ * A modular skill management system compatible with agentskills.io.
+ * Provides progressive disclosure, security scanning, and context engine integration.
+ *
+ * @module skills
+ * @example
+ * ```typescript
+ * import { getRegistry, getLoader, scanSkill } from './skills/index.js';
+ *
+ * // Scan for skills
+ * const registry = getRegistry({ localPaths: ['./skills'] });
+ * await registry.scan();
+ *
+ * // Load a skill with progressive disclosure
+ * const loader = getLoader();
+ * const skill = registry.get('my-skill');
+ * const content = await loader.loadSkill(skill, 'summary');
+ *
+ * // Security scan
+ * const report = await scanSkill(skill);
+ * ```
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export { 
+// Errors
+SkillError, } from './types.js';
+// ============================================================================
+// Parser
+// ============================================================================
+export { parseSkill, parseSkillFile, parseSkills, isSkillFile, extractSkillId, parseYaml, parseSections, validateMetadata, extractContent, } from './parser.js';
+// ============================================================================
+// Registry
+// ============================================================================
+export { SkillsRegistry, getRegistry, resetRegistry, } from './registry.js';
+// ============================================================================
+// Loader
+// ============================================================================
+export { SkillLoader, getLoader, resetLoader, } from './loader.js';
+// ============================================================================
+// Security
+// ============================================================================
+export { scanSkill, quickSecurityCheck, getSecuritySummary, formatFindings, PATTERNS, } from './security.js';
+// ============================================================================
+// Commands
+// ============================================================================
+export { registerSkillsCommands, listCommand, viewCommand, searchCommand, enableCommand, disableCommand, scanCommand, statsCommand, } from './commands.js';
+// ============================================================================
+// Context Integration (Future Enhancement)
+// ============================================================================
+// Note: Context engine integration will be implemented in a future phase
+// to avoid circular dependencies with the context-engine module.
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Current skills system version
+ */
+export const SKILLS_VERSION = '1.0.0';
+/**
+ * Default skill directories
+ */
+export const DEFAULT_SKILL_PATHS = [
+    './skills',
+    '~/.poolbot/skills',
+];
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+import { getRegistry } from './registry.js';
+import { getLoader } from './loader.js';
+import { scanSkill } from './security.js';
+/**
+ * Quick skill lookup by ID
+ */
+export function getSkill(id) {
+    return getRegistry().get(id);
+}
+/**
+ * List all available skills
+ */
+export function listSkills() {
+    return getRegistry().getAllRefs();
+}
+/**
+ * Search skills
+ */
+export function searchSkills(query) {
+    return getRegistry().search({ query });
+}
+/**
+ * Enable a skill
+ */
+export function enableSkill(id) {
+    return getRegistry().enable(id);
+}
+/**
+ * Disable a skill
+ */
+export function disableSkill(id) {
+    return getRegistry().disable(id);
+}
+/**
+ * Get skill content for context injection
+ */
+export async function getSkillForContext(skillId, config = {}) {
+    const registry = getRegistry();
+    const loader = getLoader();
+    const skill = registry.get(skillId);
+    if (!skill || !skill.enabled)
+        return null;
+    const fullConfig = {
+        skillIds: [skillId],
+        maxTokens: 4000,
+        disclosureLevel: 'summary',
+        includeLinkedFiles: false,
+        ...config,
+    };
+    return loader.prepareForContext(skill, fullConfig);
+}
+/**
+ * Run security scan on a skill
+ */
+export async function securityScanSkill(skillId) {
+    const registry = getRegistry();
+    const skill = registry.get(skillId);
+    if (!skill)
+        return null;
+    const report = await scanSkill(skill);
+    skill.securityReport = report;
+    skill.verification = report.result;
+    return report;
+}
+/**
+ * Initialize the skills system
+ *
+ * @param config - Registry configuration
+ * @returns Promise that resolves when initialization is complete
+ *
+ * @example
+ * ```typescript
+ * import { initSkills } from './skills/index.js';
+ *
+ * await initSkills({
+ *   localPaths: ['./my-skills'],
+ *   autoScan: true,
+ * });
+ * ```
+ */
+export async function initSkills(config) {
+    const registry = getRegistry(config);
+    if (config?.localPaths?.length) {
+        await registry.scan();
+    }
+}
+/**
+ * Reset the skills system (useful for testing)
+ */
+export function resetSkills() {
+    const { resetRegistry } = require('./registry.js');
+    const { resetLoader } = require('./loader.js');
+    resetRegistry();
+    resetLoader();
+}