agent-skills-cli 1.1.2 → 1.1.4

package/dist/core/conflict-detector.js

@@ -0,0 +1,339 @@
+/**
+ * Skill Conflict Detector Module
+ * Detects contradictory instructions and overlapping topics across installed skills.
+ *
+ * 3 detection strategies (no LLM required):
+ *   1. Keyword Contradiction — imperative statements that oppose each other
+ *   2. Topic Overlap         — skills covering identical topics (token waste)
+ *   3. Rule Extraction       — Do/Don't lists with conflicting directives
+ */
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, basename } from 'path';
+import matter from 'gray-matter';
+// ── Patterns ─────────────────────────────────────────────────────────────
+/** Patterns for extracting imperative directives */
+const DIRECTIVE_PATTERNS = [
+    { regex: /^\s*[-*]?\s*(?:always\s+)use\s+(.+)/i, verb: 'use' },
+    { regex: /^\s*[-*]?\s*always\s+(.+)/i, verb: 'always' },
+    { regex: /^\s*[-*]?\s*never\s+(.+)/i, verb: 'never' },
+    { regex: /^\s*[-*]?\s*avoid\s+(.+)/i, verb: 'avoid' },
+    { regex: /^\s*[-*]?\s*prefer\s+(.+)/i, verb: 'prefer' },
+    { regex: /^\s*[-*]?\s*(?:do\s+not|don'?t)\s+(.+)/i, verb: 'dont' },
+    { regex: /^\s*[-*]?\s*do\s+(.+)/i, verb: 'do' },
+];
+/** Verbs that oppose each other */
+const OPPOSING_VERBS = [
+    ['use', 'avoid'],
+    ['always', 'never'],
+    ['prefer', 'avoid'],
+    ['do', 'dont'],
+    ['use', 'dont'],
+    ['always', 'dont'],
+    ['use', 'never'],
+];
+/** Code fence language regex */
+const CODE_FENCE_RE = /```(\w+)/g;
+/** Common stop words to ignore in topic matching */
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+    'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
+    'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+    'should', 'could', 'may', 'might', 'shall', 'can', 'need', 'must',
+    'this', 'that', 'these', 'those', 'it', 'its', 'you', 'your', 'we',
+    'our', 'they', 'their', 'when', 'where', 'how', 'what', 'which',
+    'who', 'whom', 'if', 'then', 'else', 'not', 'no', 'as', 'so',
+    'than', 'too', 'very', 'just', 'about', 'up', 'out', 'all', 'also',
+    'each', 'every', 'any', 'some', 'such', 'only', 'own', 'same',
+    'use', 'using', 'used', 'make', 'sure', 'file', 'code', 'skill',
+]);
+// ── Main Entry ───────────────────────────────────────────────────────────
+/**
+ * Detect conflicts and overlaps across a set of installed skills.
+ *
+ * @param skillPaths — array of absolute paths to skill directories
+ *                     (each should contain a SKILL.md)
+ */
+export async function detectConflicts(skillPaths) {
+    // 1. Load all skills
+    const skills = [];
+    for (const p of skillPaths) {
+        const skill = await loadSkillContent(p);
+        if (skill)
+            skills.push(skill);
+    }
+    // 2. Run detection strategies
+    const conflicts = detectContradictions(skills);
+    const overlaps = detectOverlaps(skills);
+    // 3. Build summary
+    const critical = conflicts.filter(c => c.severity === 'critical').length;
+    const warnings = conflicts.filter(c => c.severity === 'warning').length;
+    const estimatedTokenWaste = overlaps.reduce((sum, o) => sum + o.tokenWaste, 0);
+    return {
+        conflicts,
+        overlaps,
+        summary: {
+            total: conflicts.length + overlaps.length,
+            critical,
+            warnings,
+            overlapCount: overlaps.length,
+            estimatedTokenWaste,
+        },
+    };
+}
+// ── Strategy 1: Keyword Contradiction ────────────────────────────────────
+/**
+ * Extract directives from all skills, then cross-compare for contradictions.
+ */
+function detectContradictions(skills) {
+    const conflicts = [];
+    for (let i = 0; i < skills.length; i++) {
+        for (let j = i + 1; j < skills.length; j++) {
+            const a = skills[i];
+            const b = skills[j];
+            for (const da of a.directives) {
+                for (const db of b.directives) {
+                    const opposition = checkOpposition(da, db);
+                    if (opposition) {
+                        conflicts.push({
+                            severity: opposition.confidence > 0.7 ? 'critical' : 'warning',
+                            skillA: a.name,
+                            skillB: b.name,
+                            category: opposition.category,
+                            description: opposition.description,
+                            lineA: da.original,
+                            lineB: db.original,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return conflicts;
+}
+/**
+ * Check if two directives oppose each other.
+ */
+function checkOpposition(a, b) {
+    // Check if verbs are opposing
+    const isOpposing = OPPOSING_VERBS.some(([v1, v2]) => (a.verb === v1 && b.verb === v2) || (a.verb === v2 && b.verb === v1));
+    if (!isOpposing)
+        return null;
+    // Check if subjects are similar (normalized comparison)
+    const similarity = subjectSimilarity(a.subject, b.subject);
+    if (similarity < 0.4)
+        return null;
+    // Determine category from subject keywords
+    const category = categorizeSubject(a.subject + ' ' + b.subject);
+    return {
+        confidence: similarity,
+        category,
+        description: `"${a.verb} ${a.subject}" conflicts with "${b.verb} ${b.subject}"`,
+    };
+}
+/**
+ * Compute similarity between two subjects (0-1).
+ * Uses normalized word overlap (Jaccard-like).
+ */
+function subjectSimilarity(a, b) {
+    const wordsA = extractWords(a);
+    const wordsB = extractWords(b);
+    if (wordsA.length === 0 || wordsB.length === 0)
+        return 0;
+    const setA = new Set(wordsA);
+    const setB = new Set(wordsB);
+    let intersection = 0;
+    for (const word of setA) {
+        if (setB.has(word))
+            intersection++;
+    }
+    const union = new Set([...setA, ...setB]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+// ── Strategy 2: Topic Overlap ────────────────────────────────────────────
+/**
+ * Detect skills that cover the same topic (duplicate instructions).
+ */
+function detectOverlaps(skills) {
+    const overlaps = [];
+    const seen = new Set();
+    for (let i = 0; i < skills.length; i++) {
+        for (let j = i + 1; j < skills.length; j++) {
+            const a = skills[i];
+            const b = skills[j];
+            const key = [a.name, b.name].sort().join('::');
+            if (seen.has(key))
+                continue;
+            // Check heading overlap
+            const headingOverlap = arrayOverlap(a.topics.headings, b.topics.headings);
+            // Check keyword overlap
+            const keywordOverlap = arrayOverlap(a.topics.keywords, b.topics.keywords);
+            // Check language overlap
+            const langOverlap = arrayOverlap(a.topics.codeLanguages, b.topics.codeLanguages);
+            // Weighted score
+            const score = headingOverlap * 0.5 + keywordOverlap * 0.35 + langOverlap * 0.15;
+            if (score > 0.35) {
+                seen.add(key);
+                // Estimate token waste: smaller skill's token count × overlap ratio
+                const tokensA = Math.ceil(a.body.length / 4);
+                const tokensB = Math.ceil(b.body.length / 4);
+                const waste = Math.round(Math.min(tokensA, tokensB) * score);
+                // Find the common topic
+                const commonHeadings = a.topics.headings.filter(h => b.topics.headings.includes(h));
+                const commonKeywords = a.topics.keywords.filter(k => b.topics.keywords.includes(k));
+                const topic = commonHeadings.length > 0
+                    ? commonHeadings.slice(0, 3).join(', ')
+                    : commonKeywords.slice(0, 5).join(', ');
+                overlaps.push({
+                    skills: [a.name, b.name],
+                    topic: topic || 'general instructions',
+                    tokenWaste: waste,
+                });
+            }
+        }
+    }
+    return overlaps;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Load a skill's content and extract directives + topics.
+ */
+async function loadSkillContent(skillPath) {
+    const skillMd = skillPath.endsWith('SKILL.md')
+        ? skillPath
+        : join(skillPath, 'SKILL.md');
+    if (!existsSync(skillMd))
+        return null;
+    try {
+        const raw = await readFile(skillMd, 'utf-8');
+        const { data, content } = matter(raw);
+        const name = data.name || basename(skillPath);
+        const directives = extractDirectives(content);
+        const topics = extractTopics(content);
+        return { name, path: skillPath, body: content, directives, topics };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract imperative directives from skill body.
+ */
+function extractDirectives(body) {
+    const directives = [];
+    const lines = body.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('```'))
+            continue;
+        for (const { regex, verb } of DIRECTIVE_PATTERNS) {
+            const match = trimmed.match(regex);
+            if (match) {
+                const subject = match[1].replace(/[.!,;:]+$/, '').trim().toLowerCase();
+                if (subject.length > 2 && subject.length < 200) {
+                    directives.push({ line: trimmed, verb, subject, original: trimmed });
+                }
+                break; // only match first pattern per line
+            }
+        }
+    }
+    return directives;
+}
+/**
+ * Extract topic signals from skill body: headings, keywords, code languages.
+ */
+function extractTopics(body) {
+    const lines = body.split('\n');
+    const headings = [];
+    const allWords = [];
+    const codeLanguages = [];
+    let inCodeBlock = false;
+    for (const line of lines) {
+        if (line.trim().startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            // Extract language from opening fence
+            if (inCodeBlock) {
+                const match = line.match(/```(\w+)/);
+                if (match && match[1]) {
+                    codeLanguages.push(match[1].toLowerCase());
+                }
+            }
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // Extract headings (## or ###)
+        const headingMatch = line.match(/^#{2,4}\s+(.+)/);
+        if (headingMatch) {
+            headings.push(headingMatch[1].toLowerCase().trim());
+        }
+        // Extract significant words
+        const words = extractWords(line);
+        allWords.push(...words);
+    }
+    // Get top keywords by frequency (skip stop words)
+    const freq = new Map();
+    for (const word of allWords) {
+        freq.set(word, (freq.get(word) || 0) + 1);
+    }
+    const keywords = [...freq.entries()]
+        .filter(([, count]) => count >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 30)
+        .map(([word]) => word);
+    return {
+        keywords,
+        headings: [...new Set(headings)],
+        codeLanguages: [...new Set(codeLanguages)],
+    };
+}
+/**
+ * Extract significant words from a line (lowercase, no stop words, min length 3).
+ */
+function extractWords(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length >= 3 && !STOP_WORDS.has(w));
+}
+/**
+ * Compute overlap ratio between two arrays (Jaccard index).
+ */
+function arrayOverlap(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    let intersection = 0;
+    for (const item of setA) {
+        if (setB.has(item))
+            intersection++;
+    }
+    const union = new Set([...setA, ...setB]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Categorize a subject string into a conflict category.
+ */
+function categorizeSubject(text) {
+    const lower = text.toLowerCase();
+    const categories = [
+        ['formatting', ['format', 'indent', 'tab', 'space', 'semicolon', 'quote', 'lint', 'prettier', 'eslint']],
+        ['architecture', ['component', 'class', 'function', 'functional', 'module', 'pattern', 'architecture', 'structure']],
+        ['testing', ['test', 'spec', 'jest', 'vitest', 'mocha', 'assert', 'mock', 'stub']],
+        ['styling', ['css', 'style', 'tailwind', 'sass', 'scss', 'styled', 'theme', 'color']],
+        ['state management', ['state', 'redux', 'zustand', 'context', 'store', 'signal', 'observable']],
+        ['dependencies', ['import', 'require', 'dependency', 'package', 'library', 'framework']],
+        ['language', ['typescript', 'javascript', 'python', 'rust', 'go', 'java', 'type', 'interface']],
+        ['security', ['auth', 'token', 'password', 'secret', 'encrypt', 'cors', 'xss', 'csrf']],
+        ['deployment', ['deploy', 'build', 'ci', 'cd', 'docker', 'kubernetes', 'vercel', 'aws']],
+        ['api', ['api', 'rest', 'graphql', 'endpoint', 'route', 'fetch', 'request', 'response']],
+    ];
+    for (const [category, keywords] of categories) {
+        if (keywords.some(kw => lower.includes(kw)))
+            return category;
+    }
+    return 'general';
+}
+//# sourceMappingURL=conflict-detector.js.map

package/dist/core/conflict-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-detector.js","sourceRoot":"","sources":["../../src/core/conflict-detector.ts"],"names":[],"mappings":"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"}

package/dist/core/context-budget.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Context Budget Manager
+ * Ranks installed skills by relevance to the current project and selects
+ * the best combination that fits within a token budget.
+ *
+ * Relevance scoring (no LLM required):
+ *   1. File extension matching   — project files vs. skill code languages
+ *   2. Dependency matching       — package.json / requirements.txt keywords
+ *   3. Keyword density           — skill keywords vs. project file names
+ *   4. Recency boost             — recently installed skills get a small bump
+ */
+export interface SkillWithRelevance {
+    /** Skill name */
+    name: string;
+    /** Path to skill directory */
+    path: string;
+    /** Estimated token count */
+    tokens: number;
+    /** Relevance score 0-100 */
+    relevance: number;
+    /** Why this relevance score */
+    reason: string;
+    /** Full SKILL.md content (for output) */
+    content: string;
+}
+export interface ContextPlan {
+    /** Skills selected to load (within budget) */
+    loaded: SkillWithRelevance[];
+    /** Skills skipped (didn't fit or too irrelevant) */
+    skipped: SkillWithRelevance[];
+    /** Total tokens used */
+    totalTokens: number;
+    /** Budget that was set */
+    budget: number;
+    /** Budget remaining */
+    budgetRemaining: number;
+}
+export interface ContextOptions {
+    /** Token budget */
+    budget: number;
+    /** Minimum relevance score to include (0-100, default 10) */
+    minRelevance?: number;
+    /** Project directory to analyze (default: process.cwd()) */
+    projectDir?: string;
+    /** Output format */
+    format?: 'text' | 'xml' | 'json';
+}
+/**
+ * Build a context plan that fits installed skills into a token budget.
+ *
+ * @param skillPaths — array of absolute paths to skill directories
+ * @param options    — budget + project analysis options
+ */
+export declare function buildContextPlan(skillPaths: string[], options: ContextOptions): Promise<ContextPlan>;
+/**
+ * Format the context plan as XML for agent consumption.
+ */
+export declare function formatContextXML(plan: ContextPlan): string;
+/**
+ * Format the context plan as JSON.
+ */
+export declare function formatContextJSON(plan: ContextPlan): string;
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/core/context-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../../src/core/context-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,MAAM,WAAW,kBAAkB;IAC/B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IACxB,8CAA8C;IAC9C,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,oDAAoD;IACpD,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC3B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;CACpC;AAuCD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAClC,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,WAAW,CAAC,CAyCtB;AA+ND;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAS1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAQ3D"}