@meowlynxsea/koi 0.1.0

package/src/skills/frontmatter.ts

@@ -0,0 +1,179 @@
+/**
+ * Frontmatter Parser for SKILL.md files
+ *
+ * Parses YAML frontmatter from skill markdown files.
+ */
+
+import yaml from "yaml";
+
+export interface RawFrontmatter {
+  // Allow any keys but also provide explicit accessors
+  [key: string]: unknown;
+  name?: unknown;
+  description?: unknown;
+  Description?: unknown;
+  when_to_use?: unknown;
+  whenToUse?: unknown;
+  "argument-hint"?: unknown;
+  argumentHint?: unknown;
+  ArgumentHint?: unknown;
+  arguments?: unknown;
+  Arguments?: unknown;
+  "allowed-tools"?: unknown;
+  allowedTools?: unknown;
+  allowed_tools?: unknown;
+  model?: unknown;
+  Model?: unknown;
+  "disable-model-invocation"?: unknown;
+  disableModelInvocation?: unknown;
+  "user-invocable"?: unknown;
+  userInvocable?: unknown;
+  hooks?: unknown;
+  Hooks?: unknown;
+  context?: unknown;
+  Context?: unknown;
+  agent?: unknown;
+  Agent?: unknown;
+  effort?: unknown;
+  Effort?: unknown;
+  paths?: unknown;
+  Paths?: unknown;
+  shell?: unknown;
+  Shell?: unknown;
+  version?: unknown;
+  Version?: unknown;
+}
+
+/**
+ * Type guard to check if a value is a plain object
+ */
+function isRecord(value: unknown): value is RawFrontmatter {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * Returns the parsed frontmatter and the remaining content
+ */
+export function parseFrontmatter(content: string): {
+  frontmatter: RawFrontmatter;
+  body: string;
+} {
+  const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  try {
+    const parsedYaml: unknown = yaml.parse(match[1]!);
+    const frontmatter: RawFrontmatter = isRecord(parsedYaml) ? parsedYaml : {};
+    const body = match[2] ?? "";
+    return { frontmatter, body };
+  } catch {
+    return { frontmatter: {}, body: content };
+  }
+}
+
+/**
+ * Convert array or string frontmatter value to array
+ */
+export function toArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map(String);
+  }
+  if (typeof value === "string") {
+    return value.split("\n").map((s) => s.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Parse frontmatter to structured fields
+ */
+export function parseFrontmatterFields(
+  frontmatter: RawFrontmatter,
+  _body: string,
+  fileName: string
+): {
+  name?: string;
+  description?: string | string[];
+  when_to_use?: string;
+  argument_hint?: string;
+  arguments?: string[];
+  allowed_tools?: string[];
+  model?: string;
+  disable_model_invocation?: boolean;
+  user_invocable?: boolean;
+  hooks?: { "pre-task"?: string[]; "post-task"?: string[] };
+  context?: "fork" | "inline";
+  agent?: string;
+  effort?: string;
+  paths?: string[];
+  shell?: { name?: string; command?: string; env?: Record<string, string> };
+  version?: string;
+} {
+  const name =
+    (frontmatter.name as string) ??
+    fileName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+
+  const description = frontmatter.description ?? frontmatter.Description;
+  const whenToUse = frontmatter.when_to_use ?? frontmatter.whenToUse;
+  const argumentHint = frontmatter["argument-hint"] ?? frontmatter.argumentHint ?? frontmatter.ArgumentHint;
+  const argumentsList = frontmatter.arguments ?? frontmatter.Arguments;
+  const allowedTools = frontmatter["allowed-tools"] ?? frontmatter.allowedTools ?? frontmatter.allowed_tools;
+  const model = frontmatter.model ?? frontmatter.Model;
+  const disableModelInvocation = frontmatter["disable-model-invocation"] ?? frontmatter.disableModelInvocation ?? false;
+  const userInvocable = frontmatter["user-invocable"] ?? frontmatter.userInvocable ?? true;
+  const hooks = frontmatter.hooks ?? frontmatter.Hooks;
+  const context = frontmatter.context ?? frontmatter.Context;
+  const agent = frontmatter.agent ?? frontmatter.Agent;
+  const effort = frontmatter.effort ?? frontmatter.Effort;
+  const paths = frontmatter.paths ?? frontmatter.Paths;
+  const shell = frontmatter.shell ?? frontmatter.Shell;
+  const version = frontmatter.version ?? frontmatter.Version;
+
+  return {
+    name,
+    description: description !== undefined ? toArray(description) : undefined,
+    when_to_use: whenToUse as string | undefined,
+    argument_hint: argumentHint as string | undefined,
+    arguments: argumentsList ? toArray(argumentsList) : undefined,
+    allowed_tools: allowedTools ? toArray(allowedTools) : undefined,
+    model: model as string | undefined,
+    disable_model_invocation: disableModelInvocation as boolean,
+    user_invocable: userInvocable as boolean,
+    hooks: hooks as { "pre-task"?: string[]; "post-task"?: string[] } | undefined,
+    context: context as "fork" | "inline" | undefined,
+    agent: agent as string | undefined,
+    effort: effort as string | undefined,
+    paths: paths ? toArray(paths) : undefined,
+    shell: shell as { name?: string; command?: string; env?: Record<string, string> } | undefined,
+    version: version as string | undefined,
+  };
+}
+
+/**
+ * Extract argument names from argument hint string
+ * e.g., "<file> <target>" -> ["file", "target"]
+ */
+export function extractArgNames(argumentHint?: string): string[] | undefined {
+  if (!argumentHint) return undefined;
+
+  const matches = argumentHint.matchAll(/<([^>]+)>/g);
+  const names: string[] = [];
+  for (const match of matches) {
+    names.push(match[1]!);
+  }
+
+  return names.length > 0 ? names : undefined;
+}
+
+/**
+ * Estimate token count for content (rough approximation)
+ */
+export function estimateTokens(content: string): number {
+  // Rough approximation: ~4 characters per token
+  return Math.ceil(content.length / 4);
+}

package/src/skills/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Skills Module
+ *
+ * Main entry point for the Skills system.
+ * Re-exports all public types and functions.
+ * 
+ * Features:
+ * - Load skills from ~/.config/koi/skills, ~/.claude/skills, and .claude/skills
+ * - SKILL.md format with YAML frontmatter
+ * - Built-in bundled skills
+ * - Conditional skills (path-based activation)
+ * - Dynamic skill discovery
+ * - Argument substitution ({{skill.args}}, <arg>)
+ */
+
+// Types
+export type {
+  SkillCommand,
+  SkillWithPath,
+  SkillSource,
+  SkillLoadedFrom,
+  BundledSkillDefinition,
+  SkillFrontmatter,
+  SkillInvocationResult,
+  ToolUseContext,
+  HooksSettings,
+  FrontmatterShell,
+  ParsedFields,
+} from "./types.js";
+
+// Core loader functions
+export {
+  loadAllSkills,
+  getAllSkills,
+  getActiveSkills,
+  getSkillByName,
+  hasSkill,
+  getSkillsBySource,
+  getSkillsPath,
+  onSkillsLoaded,
+  discoverSkillDirsForPaths,
+  addSkillDirectories,
+  activateConditionalSkillsForPaths,
+  getDynamicSkills,
+  getConditionalSkillCount,
+  resetSkillRegistry,
+} from "./loader.js";
+
+// Bundled skills
+export {
+  registerBundledSkill,
+  getBundledSkillDefinitions,
+  initBundledSkills,
+} from "./bundled.js";
+
+// Skill invocation
+export {
+  parseSkillInvocation,
+  isSkillInvocation,
+  detectSkillInvocation,
+  invokeSkill,
+  isSkillAvailable,
+  getInvokableSkills,
+  formatSkillForDisplay,
+  getSkillSuggestions,
+  getSkillCountBySource,
+  hasAnySkills,
+  createToolUseContext,
+} from "./invoke.js";
+
+// Substitution utilities
+export {
+  substituteArguments,
+  parseArgumentNames,
+  parseNamedArguments,
+} from "./substitution.js";
+
+// Components
+export { SkillsMenu, SkillsMenuStandalone } from "./SkillsMenu.js";
+
+// Re-export frontmatter utilities for advanced usage
+export {
+  parseFrontmatter,
+  parseFrontmatterFields,
+  extractArgNames,
+  estimateTokens,
+} from "./frontmatter.js";

package/src/skills/invoke.ts

@@ -0,0 +1,231 @@
+/**
+ * Skill Invocation
+ *
+ * Handles skill detection and execution from user input.
+ * Supports Claude Code's slash command format: /skill-name <args>
+ */
+
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { SkillCommand, ToolUseContext, ContentBlockParam } from "./types.js";
+import {
+  getSkillByName,
+  hasSkill,
+  getActiveSkills,
+  getAllSkills,
+} from "./loader.js";
+
+/**
+ * Parse skill name and arguments from input
+ * Supports:
+ * - /skill-name args
+ * - /"skill name" args
+ * - /skill-name (no args)
+ */
+export function parseSkillInvocation(text: string): { name: string; args: string } | null {
+  const trimmed = text.trim();
+  
+  if (!trimmed.startsWith("/")) {
+    return null;
+  }
+
+  // Handle quoted skill names: /"skill name" or /'skill name'
+  if (trimmed.startsWith('/"')) {
+    const endQuote = trimmed.indexOf('"', 2);
+    if (endQuote === -1) return null;
+    const name = trimmed.slice(2, endQuote);
+    const rest = trimmed.slice(endQuote + 1).trim();
+    return { name, args: rest };
+  }
+
+  if (trimmed.startsWith("/'")) {
+    const endQuote = trimmed.indexOf("'", 2);
+    if (endQuote === -1) return null;
+    const name = trimmed.slice(2, endQuote);
+    const rest = trimmed.slice(endQuote + 1).trim();
+    return { name, args: rest };
+  }
+
+  // Standard slash command: /name args
+  const spaceIdx = trimmed.indexOf(" ");
+  if (spaceIdx === -1) {
+    return { name: trimmed.slice(1), args: "" };
+  }
+
+  const name = trimmed.slice(1, spaceIdx);
+  const args = trimmed.slice(spaceIdx + 1).trim();
+  
+  return { name, args };
+}
+
+/**
+ * Detect if input is a skill invocation
+ */
+export function isSkillInvocation(text: string): boolean {
+  const parsed = parseSkillInvocation(text);
+  if (!parsed) return false;
+  return hasSkill(parsed.name);
+}
+
+/**
+ * Detect skill invocation and return the skill with args
+ */
+export function detectSkillInvocation(
+  text: string
+): { skill: SkillCommand; args: string } | null {
+  const parsed = parseSkillInvocation(text);
+  if (!parsed) return null;
+
+  // Try exact match first
+  let skill = getSkillByName(parsed.name);
+  
+  // If not found, try case-insensitive match
+  if (!skill) {
+    skill = getSkillByName(parsed.name.toLowerCase());
+  }
+
+  // Try matching with aliases (for bundled skills)
+  if (!skill) {
+    const allSkills = getAllSkills();
+    const nameLower = parsed.name.toLowerCase();
+    
+    for (const s of allSkills) {
+      if (s.name.toLowerCase() === nameLower) {
+        skill = s;
+        break;
+      }
+      // Check aliases if available
+      const aliases = (s as { aliases?: string[] }).aliases;
+      if (aliases?.some((a) => a.toLowerCase() === nameLower)) {
+        skill = s;
+        break;
+      }
+    }
+  }
+
+  if (!skill) return null;
+
+  return { skill, args: parsed.args };
+}
+
+/**
+ * Create a tool use context for skill execution
+ */
+export function createToolUseContext(_session: AgentSession | null): ToolUseContext {
+  return {
+    tools: {},
+    env: process.env as Record<string, unknown>,
+    cwd: process.cwd(),
+  };
+}
+
+/**
+ * Invoke a skill and get the generated prompt content
+ */
+export async function invokeSkill(
+  skill: SkillCommand,
+  args: string,
+  session: AgentSession | null
+): Promise<ContentBlockParam[]> {
+  const ctx = createToolUseContext(session);
+  return skill.getPromptForCommand(args, ctx);
+}
+
+/**
+ * Check if a skill is available for invocation
+ */
+export function isSkillAvailable(name: string): boolean {
+  return hasSkill(name);
+}
+
+/**
+ * Get all invokable skills (user invocable ones)
+ */
+export function getInvokableSkills(): SkillCommand[] {
+  return getActiveSkills().filter((skill) => skill.userInvocable);
+}
+
+/**
+ * Format skill for display
+ */
+export function formatSkillForDisplay(skill: SkillCommand): {
+  name: string;
+  description: string;
+  usage: string;
+} {
+  const usage = skill.argumentHint
+    ? `/${skill.name} ${skill.argumentHint}`
+    : `/${skill.name}`;
+
+  return {
+    name: skill.name,
+    description: skill.description,
+    usage,
+  };
+}
+
+/**
+ * Check if input might be a skill and return suggested skill names
+ */
+export function getSkillSuggestions(input: string, limit = 5): string[] {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith("/")) return [];
+  
+  const query = trimmed.slice(1).toLowerCase();
+  if (!query) return [];
+
+  const allSkills = getActiveSkills();
+  const suggestions: Array<{ skill: SkillCommand; score: number }> = [];
+
+  for (const skill of allSkills) {
+    if (!skill.userInvocable) continue;
+    
+    const nameLower = skill.name.toLowerCase();
+    let score = 0;
+
+    // Exact match
+    if (nameLower === query) {
+      score = 100;
+    }
+    // Starts with
+    else if (nameLower.startsWith(query)) {
+      score = 50;
+    }
+    // Contains
+    else if (nameLower.includes(query)) {
+      score = 25;
+    }
+
+    if (score > 0) {
+      suggestions.push({ skill, score });
+    }
+  }
+
+  // Sort by score descending, then alphabetically
+  suggestions.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.skill.name.localeCompare(b.skill.name);
+  });
+
+  return suggestions.slice(0, limit).map((s) => s.skill.name);
+}
+
+/**
+ * Get skill count by source
+ */
+export function getSkillCountBySource(): Record<string, number> {
+  const bySource = new Map<string, number>();
+  
+  for (const skill of getActiveSkills()) {
+    const count = bySource.get(skill.source) ?? 0;
+    bySource.set(skill.source, count + 1);
+  }
+
+  return Object.fromEntries(bySource);
+}
+
+/**
+ * Check if there are any skills available
+ */
+export function hasAnySkills(): boolean {
+  return getActiveSkills().length > 0;
+}