@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/skills.ts

@@ -0,0 +1,437 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
+import { minimatch } from "minimatch";
+import { homedir } from "os";
+import { basename, dirname, join, resolve } from "path";
+import { CONFIG_DIR_NAME, getAgentDir } from "../config.js";
+import type { SkillsSettings } from "./settings-manager.js";
+
+/**
+ * Standard frontmatter fields per Agent Skills spec.
+ * See: https://agentskills.io/specification#frontmatter-required
+ */
+const ALLOWED_FRONTMATTER_FIELDS = new Set([
+	"name",
+	"description",
+	"license",
+	"compatibility",
+	"metadata",
+	"allowed-tools",
+]);
+
+/** Max name length per spec */
+const MAX_NAME_LENGTH = 64;
+
+/** Max description length per spec */
+const MAX_DESCRIPTION_LENGTH = 1024;
+
+export interface SkillFrontmatter {
+	name?: string;
+	description?: string;
+	[key: string]: unknown;
+}
+
+export interface Skill {
+	name: string;
+	description: string;
+	filePath: string;
+	baseDir: string;
+	source: string;
+}
+
+export interface SkillWarning {
+	skillPath: string;
+	message: string;
+}
+
+export interface LoadSkillsResult {
+	skills: Skill[];
+	warnings: SkillWarning[];
+}
+
+type SkillFormat = "recursive" | "claude";
+
+function stripQuotes(value: string): string {
+	if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+function parseFrontmatter(content: string): { frontmatter: SkillFrontmatter; body: string; allKeys: string[] } {
+	const frontmatter: SkillFrontmatter = {};
+	const allKeys: string[] = [];
+
+	const normalizedContent = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+	if (!normalizedContent.startsWith("---")) {
+		return { frontmatter, body: normalizedContent, allKeys };
+	}
+
+	const endIndex = normalizedContent.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalizedContent, allKeys };
+	}
+
+	const frontmatterBlock = normalizedContent.slice(4, endIndex);
+	const body = normalizedContent.slice(endIndex + 4).trim();
+
+	for (const line of frontmatterBlock.split("\n")) {
+		const match = line.match(/^(\w[\w-]*):\s*(.*)$/);
+		if (match) {
+			const key = match[1];
+			const value = stripQuotes(match[2].trim());
+			allKeys.push(key);
+			if (key === "name") {
+				frontmatter.name = value;
+			} else if (key === "description") {
+				frontmatter.description = value;
+			}
+		}
+	}
+
+	return { frontmatter, body, allKeys };
+}
+
+/**
+ * Validate skill name per Agent Skills spec.
+ * Returns array of validation error messages (empty if valid).
+ */
+function validateName(name: string, parentDirName: string): string[] {
+	const errors: string[] = [];
+
+	if (name !== parentDirName) {
+		errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+	}
+
+	if (name.length > MAX_NAME_LENGTH) {
+		errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+	}
+
+	if (!/^[a-z0-9-]+$/.test(name)) {
+		errors.push(`name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)`);
+	}
+
+	if (name.startsWith("-") || name.endsWith("-")) {
+		errors.push(`name must not start or end with a hyphen`);
+	}
+
+	if (name.includes("--")) {
+		errors.push(`name must not contain consecutive hyphens`);
+	}
+
+	return errors;
+}
+
+/**
+ * Validate description per Agent Skills spec.
+ */
+function validateDescription(description: string | undefined): string[] {
+	const errors: string[] = [];
+
+	if (!description || description.trim() === "") {
+		errors.push(`description is required`);
+	} else if (description.length > MAX_DESCRIPTION_LENGTH) {
+		errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+	}
+
+	return errors;
+}
+
+/**
+ * Check for unknown frontmatter fields.
+ */
+function validateFrontmatterFields(keys: string[]): string[] {
+	const errors: string[] = [];
+	for (const key of keys) {
+		if (!ALLOWED_FRONTMATTER_FIELDS.has(key)) {
+			errors.push(`unknown frontmatter field "${key}"`);
+		}
+	}
+	return errors;
+}
+
+export interface LoadSkillsFromDirOptions {
+	/** Directory to scan for skills */
+	dir: string;
+	/** Source identifier for these skills */
+	source: string;
+}
+
+/**
+ * Load skills from a directory recursively.
+ * Skills are directories containing a SKILL.md file with frontmatter including a description.
+ */
+export function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult {
+	const { dir, source } = options;
+	return loadSkillsFromDirInternal(dir, source, "recursive");
+}
+
+function loadSkillsFromDirInternal(dir: string, source: string, format: SkillFormat): LoadSkillsResult {
+	const skills: Skill[] = [];
+	const warnings: SkillWarning[] = [];
+
+	if (!existsSync(dir)) {
+		return { skills, warnings };
+	}
+
+	try {
+		const entries = readdirSync(dir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			if (entry.name.startsWith(".")) {
+				continue;
+			}
+
+			// Skip node_modules to avoid scanning dependencies
+			if (entry.name === "node_modules") {
+				continue;
+			}
+
+			const fullPath = join(dir, entry.name);
+
+			// For symlinks, check if they point to a directory and follow them
+			let isDirectory = entry.isDirectory();
+			let isFile = entry.isFile();
+			if (entry.isSymbolicLink()) {
+				try {
+					const stats = statSync(fullPath);
+					isDirectory = stats.isDirectory();
+					isFile = stats.isFile();
+				} catch {
+					// Broken symlink, skip it
+					continue;
+				}
+			}
+
+			if (format === "recursive") {
+				// Recursive format: scan directories, look for SKILL.md files
+				if (isDirectory) {
+					const subResult = loadSkillsFromDirInternal(fullPath, source, format);
+					skills.push(...subResult.skills);
+					warnings.push(...subResult.warnings);
+				} else if (isFile && entry.name === "SKILL.md") {
+					const result = loadSkillFromFile(fullPath, source);
+					if (result.skill) {
+						skills.push(result.skill);
+					}
+					warnings.push(...result.warnings);
+				}
+			} else if (format === "claude") {
+				// Claude format: only one level deep, each directory must contain SKILL.md
+				if (!isDirectory) {
+					continue;
+				}
+
+				const skillFile = join(fullPath, "SKILL.md");
+				if (!existsSync(skillFile)) {
+					continue;
+				}
+
+				const result = loadSkillFromFile(skillFile, source);
+				if (result.skill) {
+					skills.push(result.skill);
+				}
+				warnings.push(...result.warnings);
+			}
+		}
+	} catch {}
+
+	return { skills, warnings };
+}
+
+function loadSkillFromFile(filePath: string, source: string): { skill: Skill | null; warnings: SkillWarning[] } {
+	const warnings: SkillWarning[] = [];
+
+	try {
+		const rawContent = readFileSync(filePath, "utf-8");
+		const { frontmatter, allKeys } = parseFrontmatter(rawContent);
+		const skillDir = dirname(filePath);
+		const parentDirName = basename(skillDir);
+
+		// Validate frontmatter fields
+		const fieldErrors = validateFrontmatterFields(allKeys);
+		for (const error of fieldErrors) {
+			warnings.push({ skillPath: filePath, message: error });
+		}
+
+		// Validate description
+		const descErrors = validateDescription(frontmatter.description);
+		for (const error of descErrors) {
+			warnings.push({ skillPath: filePath, message: error });
+		}
+
+		// Use name from frontmatter, or fall back to parent directory name
+		const name = frontmatter.name || parentDirName;
+
+		// Validate name
+		const nameErrors = validateName(name, parentDirName);
+		for (const error of nameErrors) {
+			warnings.push({ skillPath: filePath, message: error });
+		}
+
+		// Still load the skill even with warnings (unless description is completely missing)
+		if (!frontmatter.description || frontmatter.description.trim() === "") {
+			return { skill: null, warnings };
+		}
+
+		return {
+			skill: {
+				name,
+				description: frontmatter.description,
+				filePath,
+				baseDir: skillDir,
+				source,
+			},
+			warnings,
+		};
+	} catch {
+		return { skill: null, warnings };
+	}
+}
+
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ */
+export function formatSkillsForPrompt(skills: Skill[]): string {
+	if (skills.length === 0) {
+		return "";
+	}
+
+	const lines = [
+		"\n\nThe following skills provide specialized instructions for specific tasks.",
+		"Use the read tool to load a skill's file when the task matches its description.",
+		"",
+		"<available_skills>",
+	];
+
+	for (const skill of skills) {
+		lines.push("  <skill>");
+		lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+		lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+		lines.push("  </skill>");
+	}
+
+	lines.push("</available_skills>");
+
+	return lines.join("\n");
+}
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+export interface LoadSkillsOptions extends SkillsSettings {
+	/** Working directory for project-local skills. Default: process.cwd() */
+	cwd?: string;
+	/** Agent config directory for global skills. Default: ~/.pi/agent */
+	agentDir?: string;
+}
+
+/**
+ * Load skills from all configured locations.
+ * Returns skills and any validation warnings.
+ */
+export function loadSkills(options: LoadSkillsOptions = {}): LoadSkillsResult {
+	const {
+		cwd = process.cwd(),
+		agentDir,
+		enableCodexUser = true,
+		enableClaudeUser = true,
+		enableClaudeProject = true,
+		enablePiUser = true,
+		enablePiProject = true,
+		customDirectories = [],
+		ignoredSkills = [],
+		includeSkills = [],
+	} = options;
+
+	// Resolve agentDir - if not provided, use default from config
+	const resolvedAgentDir = agentDir ?? getAgentDir();
+
+	const skillMap = new Map<string, Skill>();
+	const realPathSet = new Set<string>();
+	const allWarnings: SkillWarning[] = [];
+	const collisionWarnings: SkillWarning[] = [];
+
+	// Check if skill name matches any of the include patterns
+	function matchesIncludePatterns(name: string): boolean {
+		if (includeSkills.length === 0) return true; // No filter = include all
+		return includeSkills.some((pattern) => minimatch(name, pattern));
+	}
+
+	// Check if skill name matches any of the ignore patterns
+	function matchesIgnorePatterns(name: string): boolean {
+		if (ignoredSkills.length === 0) return false;
+		return ignoredSkills.some((pattern) => minimatch(name, pattern));
+	}
+
+	function addSkills(result: LoadSkillsResult) {
+		allWarnings.push(...result.warnings);
+		for (const skill of result.skills) {
+			// Apply ignore filter (glob patterns) - takes precedence over include
+			if (matchesIgnorePatterns(skill.name)) {
+				continue;
+			}
+			// Apply include filter (glob patterns)
+			if (!matchesIncludePatterns(skill.name)) {
+				continue;
+			}
+
+			// Resolve symlinks to detect duplicate files
+			let realPath: string;
+			try {
+				realPath = realpathSync(skill.filePath);
+			} catch {
+				realPath = skill.filePath;
+			}
+
+			// Skip silently if we've already loaded this exact file (via symlink)
+			if (realPathSet.has(realPath)) {
+				continue;
+			}
+
+			const existing = skillMap.get(skill.name);
+			if (existing) {
+				collisionWarnings.push({
+					skillPath: skill.filePath,
+					message: `name collision: "${skill.name}" already loaded from ${existing.filePath}, skipping this one`,
+				});
+			} else {
+				skillMap.set(skill.name, skill);
+				realPathSet.add(realPath);
+			}
+		}
+	}
+
+	if (enableCodexUser) {
+		addSkills(loadSkillsFromDirInternal(join(homedir(), ".codex", "skills"), "codex-user", "recursive"));
+	}
+	if (enableClaudeUser) {
+		addSkills(loadSkillsFromDirInternal(join(homedir(), ".claude", "skills"), "claude-user", "claude"));
+	}
+	if (enableClaudeProject) {
+		addSkills(loadSkillsFromDirInternal(resolve(cwd, ".claude", "skills"), "claude-project", "claude"));
+	}
+	if (enablePiUser) {
+		addSkills(loadSkillsFromDirInternal(join(resolvedAgentDir, "skills"), "user", "recursive"));
+	}
+	if (enablePiProject) {
+		addSkills(loadSkillsFromDirInternal(resolve(cwd, CONFIG_DIR_NAME, "skills"), "project", "recursive"));
+	}
+	for (const customDir of customDirectories) {
+		addSkills(loadSkillsFromDirInternal(customDir.replace(/^~(?=$|[\\/])/, homedir()), "custom", "recursive"));
+	}
+
+	return {
+		skills: Array.from(skillMap.values()),
+		warnings: [...allWarnings, ...collisionWarnings],
+	};
+}

package/src/core/slash-commands.ts

@@ -0,0 +1,248 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+import { CONFIG_DIR_NAME, getCommandsDir } from "../config.js";
+
+/**
+ * Represents a custom slash command loaded from a file
+ */
+export interface FileSlashCommand {
+	name: string;
+	description: string;
+	content: string;
+	source: string; // e.g., "(user)", "(project)", "(project:frontend)"
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * Returns { frontmatter, content } where content has frontmatter stripped
+ */
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; content: string } {
+	const frontmatter: Record<string, string> = {};
+
+	if (!content.startsWith("---")) {
+		return { frontmatter, content };
+	}
+
+	const endIndex = content.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, content };
+	}
+
+	const frontmatterBlock = content.slice(4, endIndex);
+	const remainingContent = content.slice(endIndex + 4).trim();
+
+	// Simple YAML parsing - just key: value pairs
+	for (const line of frontmatterBlock.split("\n")) {
+		const match = line.match(/^(\w+):\s*(.*)$/);
+		if (match) {
+			frontmatter[match[1]] = match[2].trim();
+		}
+	}
+
+	return { frontmatter, content: remainingContent };
+}
+
+/**
+ * Parse command arguments respecting quoted strings (bash-style)
+ * Returns array of arguments
+ */
+export function parseCommandArgs(argsString: string): string[] {
+	const args: string[] = [];
+	let current = "";
+	let inQuote: string | null = null;
+
+	for (let i = 0; i < argsString.length; i++) {
+		const char = argsString[i];
+
+		if (inQuote) {
+			if (char === inQuote) {
+				inQuote = null;
+			} else {
+				current += char;
+			}
+		} else if (char === '"' || char === "'") {
+			inQuote = char;
+		} else if (char === " " || char === "\t") {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+		} else {
+			current += char;
+		}
+	}
+
+	if (current) {
+		args.push(current);
+	}
+
+	return args;
+}
+
+/**
+ * Substitute argument placeholders in command content
+ * Supports $1, $2, ... for positional args and $@ for all args
+ */
+export function substituteArgs(content: string, args: string[]): string {
+	let result = content;
+
+	// Replace $@ with all args joined
+	result = result.replace(/\$@/g, args.join(" "));
+
+	// Replace $1, $2, etc. with positional args
+	result = result.replace(/\$(\d+)/g, (_, num) => {
+		const index = parseInt(num, 10) - 1;
+		return args[index] ?? "";
+	});
+
+	return result;
+}
+
+/**
+ * Recursively scan a directory for .md files (and symlinks to .md files) and load them as slash commands
+ */
+function loadCommandsFromDir(
+	dir: string,
+	source: "builtin" | "user" | "project",
+	subdir: string = "",
+): FileSlashCommand[] {
+	const commands: FileSlashCommand[] = [];
+
+	if (!existsSync(dir)) {
+		return commands;
+	}
+
+	try {
+		const entries = readdirSync(dir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+
+			if (entry.isDirectory()) {
+				// Recurse into subdirectory
+				const newSubdir = subdir ? `${subdir}:${entry.name}` : entry.name;
+				commands.push(...loadCommandsFromDir(fullPath, source, newSubdir));
+			} else if ((entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md")) {
+				try {
+					const rawContent = readFileSync(fullPath, "utf-8");
+					const { frontmatter, content } = parseFrontmatter(rawContent);
+
+					const name = entry.name.slice(0, -3); // Remove .md extension
+
+					// Build source string
+					let sourceStr: string;
+					if (source === "builtin") {
+						sourceStr = subdir ? `(builtin:${subdir})` : "(builtin)";
+					} else if (source === "user") {
+						sourceStr = subdir ? `(user:${subdir})` : "(user)";
+					} else {
+						sourceStr = subdir ? `(project:${subdir})` : "(project)";
+					}
+
+					// Get description from frontmatter or first non-empty line
+					let description = frontmatter.description || "";
+					if (!description) {
+						const firstLine = content.split("\n").find((line) => line.trim());
+						if (firstLine) {
+							// Truncate if too long
+							description = firstLine.slice(0, 60);
+							if (firstLine.length > 60) description += "...";
+						}
+					}
+
+					// Append source to description
+					description = description ? `${description} ${sourceStr}` : sourceStr;
+
+					commands.push({
+						name,
+						description,
+						content,
+						source: sourceStr,
+					});
+				} catch (_error) {
+					// Silently skip files that can't be read
+				}
+			}
+		}
+	} catch (_error) {
+		// Silently skip directories that can't be read
+	}
+
+	return commands;
+}
+
+export interface LoadSlashCommandsOptions {
+	/** Working directory for project-local commands. Default: process.cwd() */
+	cwd?: string;
+	/** Agent config directory for global commands. Default: from getCommandsDir() */
+	agentDir?: string;
+}
+
+/**
+ * Load all custom slash commands from:
+ * 1. Builtin: package commands/
+ * 2. Global: agentDir/commands/
+ * 3. Project: cwd/{CONFIG_DIR_NAME}/commands/
+ */
+export function loadSlashCommands(options: LoadSlashCommandsOptions = {}): FileSlashCommand[] {
+	const resolvedCwd = options.cwd ?? process.cwd();
+	const resolvedAgentDir = options.agentDir ?? getCommandsDir();
+
+	const commands: FileSlashCommand[] = [];
+	const seenNames = new Set<string>();
+
+	// 1. Builtin commands (from package)
+	const builtinDir = join(import.meta.dir, "../commands");
+	if (existsSync(builtinDir)) {
+		const builtinCommands = loadCommandsFromDir(builtinDir, "builtin");
+		for (const cmd of builtinCommands) {
+			if (!seenNames.has(cmd.name)) {
+				commands.push(cmd);
+				seenNames.add(cmd.name);
+			}
+		}
+	}
+
+	// 2. Load global commands from agentDir/commands/
+	// Note: if agentDir is provided, it should be the agent dir, not the commands dir
+	const globalCommandsDir = options.agentDir ? join(options.agentDir, "commands") : resolvedAgentDir;
+	const globalCommands = loadCommandsFromDir(globalCommandsDir, "user");
+	for (const cmd of globalCommands) {
+		if (!seenNames.has(cmd.name)) {
+			commands.push(cmd);
+			seenNames.add(cmd.name);
+		}
+	}
+
+	// 3. Load project commands from cwd/{CONFIG_DIR_NAME}/commands/
+	const projectCommandsDir = resolve(resolvedCwd, CONFIG_DIR_NAME, "commands");
+	const projectCommands = loadCommandsFromDir(projectCommandsDir, "project");
+	for (const cmd of projectCommands) {
+		if (!seenNames.has(cmd.name)) {
+			commands.push(cmd);
+			seenNames.add(cmd.name);
+		}
+	}
+
+	return commands;
+}
+
+/**
+ * Expand a slash command if it matches a file-based command.
+ * Returns the expanded content or the original text if not a slash command.
+ */
+export function expandSlashCommand(text: string, fileCommands: FileSlashCommand[]): string {
+	if (!text.startsWith("/")) return text;
+
+	const spaceIndex = text.indexOf(" ");
+	const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+	const argsString = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+
+	const fileCommand = fileCommands.find((cmd) => cmd.name === commandName);
+	if (fileCommand) {
+		const args = parseCommandArgs(argsString);
+		return substituteArgs(fileCommand.content, args);
+	}
+
+	return text;
+}