pi-harness-runtime 1.1.95 → 1.1.97

package/packages/skills/src/linter.ts

@@ -0,0 +1,371 @@
+/**
+ * Skill Linter
+ * 
+ * Hermes-style quality checks for skills.
+ * Ensures skills capture "lessons, not logs".
+ */
+
+import type { Skill, LintResult, LintRule, LintSeverity } from "./types.js";
+
+/**
+ * Hermes-style linter rules
+ */
+export const LINTER_RULES: LintRule[] = [
+  // === Quality Rules ===
+  
+  {
+    name: "incident-log-shape",
+    description: "Body contains too many PR/issue references (looks like incident log)",
+    severity: "warning",
+    check: (skill: Skill): LintResult | null => {
+      // Count PR/issue references like #123, PR #456, issue #789
+      const prIssueRefs = skill.body.match(/(?:PR|issue|#)\s*\d+/gi) ?? [];
+      if (prIssueRefs.length > 5) {
+        return {
+          rule: "incident-log-shape",
+          severity: "warning",
+          message: `Found ${prIssueRefs.length} PR/issue references. Skills should capture rules, not incident logs.`,
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "references-sprawl",
+    description: "Too many reference files (>60)",
+    severity: "error",
+    check: (skill: Skill): LintResult | null => {
+      if (skill.references.length > 60) {
+        return {
+          rule: "references-sprawl",
+          severity: "error",
+          message: `Found ${skill.references.length} reference files. Skills should consolidate references.`,
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "oversized-body",
+    description: "SKILL.md exceeds 24k characters",
+    severity: "warning",
+    check: (skill: Skill): LintResult | null => {
+      if (skill.body.length > 24000) {
+        return {
+          rule: "oversized-body",
+          severity: "warning",
+          message: `SKILL.md body is ${skill.body.length} chars (exceeds 24k). Consider splitting into references.`,
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "missing-pitfalls",
+    description: "No pitfalls with 'why' explanations",
+    severity: "info",
+    check: (skill: Skill): LintResult | null => {
+      const hasPitfalls = skill.hermes?.pitfalls && skill.hermes.pitfalls.length > 0;
+      const hasWhy = skill.body.toLowerCase().includes("why");
+      
+      if (!hasPitfalls && !hasWhy) {
+        return {
+          rule: "missing-pitfalls",
+          severity: "info",
+          message: "No pitfalls found. Consider documenting common mistakes and why they happen.",
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "missing-examples",
+    description: "No examples provided",
+    severity: "info",
+    check: (skill: Skill): LintResult | null => {
+      if (skill.examples.length === 0) {
+        return {
+          rule: "missing-examples",
+          severity: "info",
+          message: "No examples found. Consider adding example files to demonstrate the skill.",
+        };
+      }
+      return null;
+    },
+  },
+
+  // === pi.dev Compatibility Rules ===
+
+  {
+    name: "missing-description",
+    description: "No description in frontmatter",
+    severity: "error",
+    check: (skill: Skill): LintResult | null => {
+      if (!skill.frontmatter.description || skill.frontmatter.description.length < 10) {
+        return {
+          rule: "missing-description",
+          severity: "error",
+          message: "Missing or too short description. The description determines when the model considers loading the skill.",
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "invalid-name",
+    description: "Name contains invalid characters",
+    severity: "error",
+    check: (skill: Skill): LintResult | null => {
+      const nameRegex = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+      if (!nameRegex.test(skill.frontmatter.name)) {
+        return {
+          rule: "invalid-name",
+          severity: "error",
+          message: `Invalid skill name '${skill.frontmatter.name}'. Must be kebab-case (e.g., 'code-review').`,
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "name-mismatch",
+    description: "Directory name doesn't match skill name",
+    severity: "warning",
+    check: (skill: Skill): LintResult | null => {
+      const dirName = skill.path.split("/").pop() ?? "";
+      if (dirName !== skill.frontmatter.name && dirName !== "") {
+        return {
+          rule: "name-mismatch",
+          severity: "warning",
+          message: `Directory name '${dirName}' differs from skill name '${skill.frontmatter.name}'. Consider matching them for portability.`,
+        };
+      }
+      return null;
+    },
+  },
+
+  // === Hermes-Specific Rules ===
+
+  {
+    name: "missing-triggers",
+    description: "No triggers defined for auto-matching",
+    severity: "info",
+    check: (skill: Skill): LintResult | null => {
+      const hasTriggers = skill.hermes?.triggers && skill.hermes.triggers.length > 0;
+      if (!hasTriggers) {
+        return {
+          rule: "missing-triggers",
+          severity: "info",
+          message: "No triggers defined. The skill relies only on description matching.",
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "low-confidence",
+    description: "Skill has low confidence score",
+    severity: "info",
+    check: (skill: Skill): LintResult | null => {
+      const confidence = skill.hermes?.confidence;
+      if (confidence !== undefined && confidence < 0.5) {
+        return {
+          rule: "low-confidence",
+          severity: "info",
+          message: `Low confidence score (${confidence}). Consider validating this skill pattern.`,
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "unused-skill",
+    description: "Skill has never been used",
+    severity: "info",
+    check: (skill: Skill): LintResult | null => {
+      const usageCount = skill.hermes?.usage_count ?? 0;
+      if (usageCount === 0 && skill.hermes?.created_at) {
+        return {
+          rule: "unused-skill",
+          severity: "info",
+          message: "This skill has never been used. Consider testing or archiving it.",
+        };
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "generic-description",
+    description: "Description is too generic",
+    severity: "warning",
+    check: (skill: Skill): LintResult | null => {
+      const genericPhrases = [
+        "helps with",
+        "useful for",
+        "does things",
+        "stuff",
+        "things",
+      ];
+      const descLower = skill.frontmatter.description.toLowerCase();
+      
+      for (const phrase of genericPhrases) {
+        if (descLower.includes(phrase)) {
+          return {
+            rule: "generic-description",
+            severity: "warning",
+            message: `Description contains generic phrase '${phrase}'. Be specific about what the skill does and when to use it.`,
+          };
+        }
+      }
+      return null;
+    },
+  },
+
+  {
+    name: "log-like-content",
+    description: "Body contains log-like content (timestamps, repeated patterns)",
+    severity: "warning",
+    check: (skill: Skill): LintResult | null => {
+      // Check for log patterns
+      const logPatterns = [
+        /\d{4}-\d{2}-\d{2}/,  // dates
+        /\d{2}:\d{2}:\d{2}/,   // timestamps
+        /^(?:INFO|ERROR|WARN|DEBUG)/m,  // log levels
+        /^\d+\.\s/m,           // numbered lists (too detailed)
+      ];
+      
+      let matchCount = 0;
+      for (const pattern of logPatterns) {
+        if (pattern.test(skill.body)) {
+          matchCount++;
+        }
+      }
+      
+      if (matchCount >= 2) {
+        return {
+          rule: "log-like-content",
+          severity: "warning",
+          message: "Body contains log-like patterns. Skills should capture procedures and rules, not logs.",
+        };
+      }
+      return null;
+    },
+  },
+];
+
+/**
+ * Lint a skill
+ */
+export function lintSkill(skill: Skill, rules?: LintRule[]): LintResult[] {
+  const rulesToUse = rules ?? LINTER_RULES;
+  const results: LintResult[] = [];
+
+  for (const rule of rulesToUse) {
+    try {
+      const result = rule.check(skill);
+      if (result) {
+        results.push(result);
+      }
+    } catch (err) {
+      results.push({
+        rule: rule.name,
+        severity: "error",
+        message: `Linter error: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Lint a skill and return formatted output
+ */
+export function lintSkillFormatted(skill: Skill, rules?: LintRule[]): string {
+  const results = lintSkill(skill, rules);
+  
+  if (results.length === 0) {
+    return `✓ ${skill.id}: No issues found`;
+  }
+
+  const lines: string[] = [`✗ ${skill.id}:`];
+  
+  for (const result of results) {
+    const icon = result.severity === "error" ? "✗" : result.severity === "warning" ? "⚠" : "ℹ";
+    lines.push(`  ${icon} [${result.severity}] ${result.rule}: ${result.message}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Get lint summary for multiple skills
+ */
+export function lintSkillsSummary(skills: Skill[]): {
+  total: number;
+  passed: number;
+  failed: number;
+  bySeverity: Record<LintSeverity, number>;
+  byRule: Record<string, number>;
+} {
+  const summary = {
+    total: skills.length,
+    passed: 0,
+    failed: 0,
+    bySeverity: { error: 0, warning: 0, info: 0 } as Record<LintSeverity, number>,
+    byRule: {} as Record<string, number>,
+  };
+
+  for (const skill of skills) {
+    const results = lintSkill(skill);
+    
+    if (results.length === 0) {
+      summary.passed++;
+    } else {
+      summary.failed++;
+      for (const result of results) {
+        summary.bySeverity[result.severity]++;
+        summary.byRule[result.rule] = (summary.byRule[result.rule] ?? 0) + 1;
+      }
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Create custom lint rule
+ */
+export function createLintRule(
+  name: string,
+  description: string,
+  severity: LintSeverity,
+  check: (skill: Skill) => LintResult | null
+): LintRule {
+  return { name, description, severity, check };
+}
+
+/**
+ * Filter lint results by severity
+ */
+export function filterLintResults(
+  results: LintResult[],
+  minSeverity: LintSeverity
+): LintResult[] {
+  const severityOrder: LintSeverity[] = ["info", "warning", "error"];
+  const minIndex = severityOrder.indexOf(minSeverity);
+  
+  return results.filter((result) => {
+    const resultIndex = severityOrder.indexOf(result.severity);
+    return resultIndex >= minIndex;
+  });
+}

package/packages/skills/src/loader.ts

@@ -0,0 +1,335 @@
+/**
+ * Skill Registry
+ * 
+ * Stores and manages skills with progressive disclosure.
+ * Based on pi.dev Agent Skills specification.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  Skill,
+  SkillIndex,
+  SkillIndexEntry,
+  MatchOptions,
+  MatchResult,
+  LoadOptions,
+  LoadedSkill,
+  DEFAULT_SKILLS_CONFIG,
+} from "./types.js";
+import { parseSkillFile, scanSkillDirectory } from "./parser.js";
+
+/**
+ * Skill Registry - manages loaded and indexed skills
+ */
+export class SkillRegistry {
+  private skills: Map<string, Skill> = new Map();
+  private index: SkillIndex = { entries: [], loadedAt: 0 };
+  private loading: Map<string, Promise<Skill>> = new Map();
+
+  /**
+   * Register a skill
+   */
+  register(skill: Skill): void {
+    this.skills.set(skill.id, skill);
+    this.updateIndex(skill);
+  }
+
+  /**
+   * Unregister a skill by ID
+   */
+  unregister(skillId: string): boolean {
+    const skill = this.skills.get(skillId);
+    if (skill) {
+      this.skills.delete(skillId);
+      this.index.entries = this.index.entries.filter(
+        (e) => e.id !== skillId
+      );
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get a skill by ID
+   */
+  get(skillId: string): Skill | undefined {
+    return this.skills.get(skillId);
+  }
+
+  /**
+   * List all registered skills
+   */
+  list(): Skill[] {
+    return Array.from(this.skills.values());
+  }
+
+  /**
+   * Get skill index (lightweight)
+   */
+  getIndex(): SkillIndex {
+    return this.index;
+  }
+
+  /**
+   * Find skills matching a trigger/query
+   */
+  find(query: string, options?: MatchOptions): MatchResult[] {
+    const results: MatchResult[] = [];
+    const threshold = options?.threshold ?? 0.3;
+    const queryLower = query.toLowerCase();
+
+    for (const skill of this.skills.values()) {
+      // Skip disabled skills if requested
+      if (
+        !options?.includeDisabled &&
+        skill.frontmatter.disable_model_invocation
+      ) {
+        continue;
+      }
+
+      let score = 0;
+      const matchedTriggers: string[] = [];
+
+      // Check name match
+      if (skill.id.toLowerCase().includes(queryLower)) {
+        score += 0.8;
+        matchedTriggers.push(`name:${skill.id}`);
+      }
+
+      // Check description match
+      if (skill.frontmatter.description.toLowerCase().includes(queryLower)) {
+        score += 0.5;
+        matchedTriggers.push("description");
+      }
+
+      // Check triggers
+      if (skill.hermes?.triggers) {
+        for (const trigger of skill.hermes.triggers) {
+          if (trigger.toLowerCase().includes(queryLower)) {
+            score += 0.9;
+            matchedTriggers.push(`trigger:${trigger}`);
+          }
+          // Also check regex-style triggers
+          try {
+            const regex = new RegExp(trigger, "i");
+            if (regex.test(query)) {
+              score += 0.9;
+              matchedTriggers.push(`regex:${trigger}`);
+            }
+          } catch {
+            // Invalid regex, skip
+          }
+        }
+      }
+
+      // Check tags
+      if (skill.hermes?.anti_patterns) {
+        for (const anti of skill.hermes.anti_patterns) {
+          if (anti.toLowerCase().includes(queryLower)) {
+            score += 0.3;
+            matchedTriggers.push("anti-pattern");
+          }
+        }
+      }
+
+      // Usage bonus
+      if (skill.hermes?.usage_count && skill.hermes.usage_count > 0) {
+        score += Math.min(0.2, skill.hermes.usage_count * 0.01);
+      }
+
+      if (score >= threshold) {
+        results.push({ skill, score, matchedTriggers });
+      }
+    }
+
+    // Sort results
+    const sortBy = options?.sortBy ?? "score";
+    results.sort((a, b) => {
+      if (sortBy === "score") return b.score - a.score;
+      if (sortBy === "usage") {
+        const aUsage = a.skill.hermes?.usage_count ?? 0;
+        const bUsage = b.skill.hermes?.usage_count ?? 0;
+        return bUsage - aUsage;
+      }
+      return a.skill.id.localeCompare(b.skill.id);
+    });
+
+    return results;
+  }
+
+  /**
+   * Find best matching skill for a query
+   */
+  findBestMatch(query: string, options?: MatchOptions): MatchResult | null {
+    const results = this.find(query, { ...options, threshold: 0 });
+    return results[0] ?? null;
+  }
+
+  /**
+   * Load a skill's full content (progressive disclosure)
+   */
+  async load(skillId: string, options?: LoadOptions): Promise<LoadedSkill | null> {
+    const skill = this.skills.get(skillId);
+    if (!skill) {
+      return null;
+    }
+
+    // If already loaded, return cached
+    if (skill.loaded && !options?.loadReferences && !options?.loadExamples) {
+      return skill as LoadedSkill;
+    }
+
+    // Check if already loading
+    if (this.loading.has(skillId)) {
+      return this.loading.get(skillId) as Promise<Skill>;
+    }
+
+    // Load the skill
+    const loadPromise = this.loadSkill(skill, options);
+    this.loading.set(skillId, loadPromise);
+
+    try {
+      const loadedSkill = await loadPromise;
+      this.loading.delete(skillId);
+      return loadedSkill;
+    } catch (err) {
+      this.loading.delete(skillId);
+      throw err;
+    }
+  }
+
+  /**
+   * Load skill content from disk
+   */
+  private async loadSkill(
+    skill: Skill,
+    options?: LoadOptions
+  ): Promise<LoadedSkill> {
+    const loadedSkill: LoadedSkill = { ...skill };
+    const skillMdPath = join(skill.path, "SKILL.md");
+
+    // Re-parse to get fresh content
+    if (existsSync(skillMdPath)) {
+      const parsed = parseSkillFile(skillMdPath);
+      loadedSkill.body = parsed.body;
+      loadedSkill.frontmatter = parsed.frontmatter;
+      loadedSkill.hermes = parsed.hermes;
+    }
+
+    // Load references if requested
+    if (options?.loadReferences) {
+      loadedSkill.referencesContent = new Map();
+      for (const ref of skill.references) {
+        if (existsSync(ref.path)) {
+          try {
+            const content = readFileSync(ref.path, "utf-8");
+            loadedSkill.referencesContent.set(ref.name, content);
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    }
+
+    // Load examples if requested
+    if (options?.loadExamples) {
+      loadedSkill.examplesContent = new Map();
+      for (const example of skill.examples) {
+        if (existsSync(example.path)) {
+          try {
+            const content = readFileSync(example.path, "utf-8");
+            loadedSkill.examplesContent.set(example.name, content);
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    }
+
+    // Mark as loaded
+    loadedSkill.loaded = true;
+    loadedSkill.lastUsed = Date.now();
+
+    // Update usage count
+    if (loadedSkill.hermes) {
+      loadedSkill.hermes.usage_count =
+        (loadedSkill.hermes.usage_count ?? 0) + 1;
+    }
+
+    // Update in registry
+    this.skills.set(skill.id, loadedSkill);
+
+    return loadedSkill;
+  }
+
+  /**
+   * Update skill index entry
+   */
+  private updateIndex(skill: Skill): void {
+    // Remove existing entry if present
+    this.index.entries = this.index.entries.filter(
+      (e) => e.id !== skill.id
+    );
+
+    // Add new entry
+    this.index.entries.push({
+      id: skill.id,
+      name: skill.frontmatter.name,
+      description: skill.frontmatter.description,
+      path: skill.path,
+      version: skill.frontmatter.version,
+      triggers: skill.hermes?.triggers,
+      loaded: skill.loaded,
+    });
+
+    // Update load time
+    this.index.loadedAt = Date.now();
+  }
+
+  /**
+   * Clear all skills
+   */
+  clear(): void {
+    this.skills.clear();
+    this.index = { entries: [], loadedAt: 0 };
+    this.loading.clear();
+  }
+
+  /**
+   * Get count of registered skills
+   */
+  get size(): number {
+    return this.skills.size;
+  }
+
+  /**
+   * Check if skill exists
+   */
+  has(skillId: string): boolean {
+    return this.skills.has(skillId);
+  }
+}
+
+/**
+ * Create a new skill registry
+ */
+export function createSkillRegistry(): SkillRegistry {
+  return new SkillRegistry();
+}
+
+/**
+ * Global skill registry instance (singleton)
+ */
+let globalRegistry: SkillRegistry | null = null;
+
+export function getGlobalSkillRegistry(): SkillRegistry {
+  if (!globalRegistry) {
+    globalRegistry = createSkillRegistry();
+  }
+  return globalRegistry;
+}
+
+export function setGlobalSkillRegistry(registry: SkillRegistry): void {
+  globalRegistry = registry;
+}