pi-crew 0.9.53 → 0.9.55

package/src/skills/discover-skills.ts

@@ -0,0 +1,203 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+// peer-dep.ts resolves @earendil-works/pi-coding-agent robustly across install
+// layouts. See src/runtime/peer-dep.ts (split-scope install fix).
+import { getAgentDir } from "../runtime/peer-dep.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { parseSkillFrontmatter, type SkillValidationError, validateSkillFrontmatter } from "./validate.ts";
+
+const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+
+const CACHE_TTL_MS = 30_000; // 30 seconds
+let cache: { skills: SkillDescriptor[]; cachedAt: number; cwd: string } | null = null;
+
+export interface SkillDescriptor {
+	name: string;
+	description: string;
+	/**
+	 * Source of the skill. F6 (v0.7.9) adds the Agent Skills spec roots:
+	 * - `project-pi` / `user-pi` — Pi's standard `.pi/skills/`
+	 * - `project-agents` / `user-agents` — cross-tool Agent Skills spec (`.agents/skills/`)
+	 * The original `project` / `package` are kept for back-compat.
+	 */
+	source: "project" | "package" | "project-pi" | "user-pi" | "project-agents" | "user-agents";
+	path: string;
+}
+
+/**
+ * F6 (v0.7.9): discover skills from all roots (matching pi-subagents' skill-loader
+ * so users authoring skills under either convention find them).
+ *
+ * IMPORTANT — inventory vs injection (SEC-003): this function returns EVERY
+ * skill found across roots (NO first-wins dedup) because it feeds the capability
+ * INVENTORY, which intentionally surfaces all skills (incl. project shadows) for
+ * transparency; `capability-inventory.ts` then marks project/user items that
+ * shadow a package/builtin one and re-sorts by id.
+ *
+ * The actual skill-content INJECTION path is separate: `skill-instructions.ts`
+ * `candidateSkillDirs` + `readSkillMarkdown` use first-wins with PACKAGE FIRST
+ * (SEC-003 fix, regression-tested in test/unit/skill-instructions.test.ts) so a
+ * project skill can NEVER override a trusted package skill's content in worker
+ * prompts. The package-first order below mirrors that injection path for
+ * consistency/defense-in-depth.
+ *
+ * Roots:
+ *   1. PACKAGE_SKILLS_DIR        (bundled, trusted)
+ *   2. <cwd>/.pi/skills          (project, Pi standard)
+ *   3. <cwd>/.agents/skills      (project, Agent Skills spec — agentskills.io)
+ *   4. <cwd>/skills              (project, legacy pi-crew convention)
+ *   5. <getAgentDir>/skills      (user, Pi standard)
+ *   6. <homedir>/.agents/skills  (user, Agent Skills spec)
+ *   7. <homedir>/.pi/skills      (user, legacy Pi — pre-standard)
+ */
+function listSkillDirs(cwd: string): Array<{ root: string; source: SkillDescriptor["source"] }> {
+	return [
+		{ root: PACKAGE_SKILLS_DIR, source: "package" },
+		{ root: path.resolve(cwd, ".pi", "skills"), source: "project-pi" },
+		{
+			root: path.resolve(cwd, ".agents", "skills"),
+			source: "project-agents",
+		},
+		{ root: path.resolve(cwd, "skills"), source: "project" },
+		{ root: path.join(getAgentDir(), "skills"), source: "user-pi" },
+		{
+			root: path.join(os.homedir(), ".agents", "skills"),
+			source: "user-agents",
+		},
+		{ root: path.join(os.homedir(), ".pi", "skills"), source: "user-pi" },
+	];
+}
+
+// ── Diagnostics (L3) ──────────────────────────────────────────────────────────
+// Module-level buffer populated each `discoverSkills()` call. Cleared at the
+// start of every call so callers see only the most recent run's diagnostics.
+// Surfaced via `getLastDiscoveryDiagnostics()` so capability-inventory and
+// other consumers can convert silent exclusions into visible feedback.
+let lastDiagnostics: SkillValidationError[] = [];
+
+export function getLastDiscoveryDiagnostics(): SkillValidationError[] {
+	return lastDiagnostics;
+}
+
+/**
+ * Parse frontmatter defensively. Falls back to the legacy line-prefix match
+ * if YAML parsing fails — preserves back-compat for malformed but readable
+ * SKILL.md files that pre-date the validator (we record a diagnostic in that
+ * case but still return the description we could salvage).
+ */
+function readDescription(content: string): {
+	description: string;
+	parseError: string | null;
+} {
+	const parsed = parseSkillFrontmatter(content);
+	if (parsed.ok) {
+		const d = parsed.data.description;
+		return {
+			description: typeof d === "string" ? d : "",
+			parseError: null,
+		};
+	}
+	// YAML parse failed — fall back to legacy line-prefix match so we don't
+	// regress existing skills whose frontmatter the old parser could read.
+	const legacyMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (legacyMatch) {
+		const line = legacyMatch[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+		const fallback = line?.slice("description:".length).trim() ?? "";
+		return { description: fallback, parseError: parsed.error };
+	}
+	return { description: "", parseError: parsed.error };
+}
+
+export function discoverSkills(cwd: string): SkillDescriptor[] {
+	if (cache && cache.cwd === cwd && Date.now() - cache.cachedAt < CACHE_TTL_MS) return cache.skills;
+	const results: SkillDescriptor[] = [];
+	const diagnostics: SkillValidationError[] = [];
+	for (const dir of listSkillDirs(cwd)) {
+		if (!fs.existsSync(dir.root)) continue;
+		try {
+			for (const entry of fs.readdirSync(dir.root, {
+				withFileTypes: true,
+			})) {
+				if (!entry.isDirectory()) continue;
+				if (!isSafePathId(entry.name)) continue;
+				const skillDirPath = path.join(dir.root, entry.name);
+				try {
+					if (fs.lstatSync(skillDirPath).isSymbolicLink()) continue;
+				} catch {
+					continue;
+				}
+				const skillMdRelative = path.join(entry.name, "SKILL.md");
+				let skillMdPath: string;
+				try {
+					// F-08: intentionally KEPT on resolveContainedPath (not migrated to
+					// resolveRealContainedPath). This is the lenient containment pre-check;
+					// the strict resolveRealContainedPath call below has an explicit
+					// fallback to this lenient path for skills under non-exempted
+					// symlinked system dirs. Migrating here would skip those skills
+					// instead of discovering them via the fallback.
+					skillMdPath = resolveContainedPath(dir.root, skillMdRelative);
+				} catch {
+					continue;
+				}
+				if (!fs.existsSync(skillMdPath)) continue;
+				try {
+					if (fs.lstatSync(skillMdPath).isSymbolicLink()) continue;
+				} catch {
+					continue;
+				}
+				let description = "";
+				try {
+					let readPath = skillMdPath;
+					try {
+						readPath = resolveRealContainedPath(dir.root, skillMdRelative);
+						skillMdPath = readPath;
+					} catch {
+						// resolveRealContainedPath may fail for symlinked system paths
+						// (e.g. macOS /var → /private/var). Fall through with un-resolved path.
+					}
+					const content = fs.readFileSync(readPath, "utf-8");
+					const { description: desc, parseError } = readDescription(content);
+					description = desc;
+					if (parseError) {
+						diagnostics.push({
+							path: path.dirname(skillMdPath),
+							field: "frontmatter",
+							reason: parseError,
+							severity: "error",
+						});
+					}
+				} catch (error) {
+					logInternalError("discoverSkills.readSkill", error, `skill=${entry.name}`);
+				}
+				results.push({
+					name: entry.name,
+					description,
+					source: dir.source,
+					path: skillMdPath,
+				});
+			}
+		} catch (error) {
+			logInternalError("discoverSkills.readdir", error, `root=${dir.root}`);
+		}
+	}
+	// L3: strict validation pass after we've collected every (skill, source)
+	// candidate. Excludes malformed skills (HYBRID policy: missing/malformed
+	// `name`/`description` hard-fail; unknown props warn). Diagnostics are
+	// always recorded, including for skills that PASSED validation but had
+	// unknown-prop warnings.
+	const filtered: SkillDescriptor[] = [];
+	for (const skill of results) {
+		const validation = validateSkillFrontmatter(path.dirname(skill.path));
+		if (validation.ok) {
+			filtered.push(skill);
+		} else {
+			diagnostics.push(...validation.errors);
+		}
+	}
+	lastDiagnostics = diagnostics;
+	cache = { skills: filtered, cachedAt: Date.now(), cwd };
+	return filtered;
+}

package/src/skills/skill-templates.ts

@@ -0,0 +1,456 @@
+/**
+ * Template-based skill initialization for pi-crew.
+ *
+ * Provides builtin skill templates that can be instantiated with project-specific
+ * variables to produce ready-to-use SKILL.md files.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SkillVariable {
+	/** Variable name used as placeholder key in the template body, e.g. "language". */
+	name: string;
+	/** Human-readable description of what this variable controls. */
+	description: string;
+	/** When true the caller must supply a value (no default available). */
+	required: boolean;
+	/** Default value used when the variable is optional and no value is supplied. */
+	defaultValue?: string;
+	/** If set, the supplied value must be one of these strings. */
+	options?: string[];
+}
+
+export interface SkillTemplate {
+	/** Unique template identifier, e.g. "code-review". */
+	id: string;
+	/** Human-readable name. */
+	name: string;
+	/** Short description of the skill this template produces. */
+	description: string;
+	/** Category for grouping (e.g. "quality", "testing", "documentation"). */
+	category: string;
+	/** Template variables referenced via {varName} in the body. */
+	variables: SkillVariable[];
+	/** Markdown template body with {variableName} placeholders. */
+	body: string;
+	/** Hard rules the instantiated skill must follow. */
+	guardrails: string[];
+}
+
+export interface InstantiatedSkill {
+	/** Suggested filename, e.g. "code-review.SKILL.md". */
+	filename: string;
+	/** Fully rendered markdown content. */
+	content: string;
+}
+
+// ---------------------------------------------------------------------------
+// Builtin templates
+// ---------------------------------------------------------------------------
+
+const CODE_REVIEW_TEMPLATE: SkillTemplate = {
+	id: "code-review",
+	name: "Code Review",
+	description: "Systematic code review skill with configurable language and focus areas.",
+	category: "quality",
+	variables: [
+		{
+			name: "language",
+			description: "Primary programming language of the codebase",
+			required: true,
+			options: ["TypeScript", "JavaScript", "Python", "Rust", "Go", "Java", "C#", "Other"],
+		},
+		{
+			name: "focusAreas",
+			description: "Comma-separated list of review focus areas",
+			required: false,
+			defaultValue: "correctness, readability, performance",
+		},
+		{
+			name: "severityThreshold",
+			description: "Minimum severity level to report",
+			required: false,
+			defaultValue: "warning",
+			options: ["info", "warning", "error", "critical"],
+		},
+	],
+	body: [
+		"---",
+		"description: Automated code review for {language} projects",
+		"---",
+		"",
+		"# Code Review Skill",
+		"",
+		"You are a code reviewer specializing in **{language}**.",
+		"",
+		"## Focus Areas",
+		"",
+		"Prioritize the following aspects (in order):",
+		"",
+		"{focusAreas}",
+		"",
+		"## Severity Threshold",
+		"",
+		"Only surface issues at or above **{severityThreshold}** severity.",
+		"",
+		"## Process",
+		"",
+		"1. Read the full diff / files before commenting.",
+		"2. Classify each finding by severity.",
+		"3. Provide actionable suggestions with code examples where helpful.",
+		"4. Summarize overall quality and risk assessment.",
+	].join("\n"),
+	guardrails: [
+		"Do not approve code you have not fully read.",
+		"Do not comment on style issues that are already handled by a linter.",
+		"Do not suggest changes without explaining the reasoning.",
+	],
+};
+
+const TESTING_TEMPLATE: SkillTemplate = {
+	id: "testing",
+	name: "Testing",
+	description: "Test writing skill with configurable framework and coverage targets.",
+	category: "testing",
+	variables: [
+		{
+			name: "framework",
+			description: "Testing framework to use",
+			required: true,
+			options: ["vitest", "jest", "mocha", "pytest", "go-test", "cargo-test", "Other"],
+		},
+		{
+			name: "coverageTarget",
+			description: "Target coverage percentage",
+			required: false,
+			defaultValue: "80",
+		},
+		{
+			name: "testType",
+			description: "Primary type of tests to write",
+			required: false,
+			defaultValue: "unit",
+			options: ["unit", "integration", "e2e", "all"],
+		},
+	],
+	body: [
+		"---",
+		"description: Write tests using {framework} with {coverageTarget}% coverage target",
+		"---",
+		"",
+		"# Testing Skill",
+		"",
+		"You are a test engineer writing **{testType}** tests using **{framework}**.",
+		"",
+		"## Coverage Target",
+		"",
+		"Aim for at least **{coverageTarget}%** code coverage.",
+		"",
+		"## Guidelines",
+		"",
+		"1. Write descriptive test names that explain the expected behavior.",
+		"2. Follow the Arrange-Act-Assert pattern.",
+		"3. Test edge cases and error paths, not just the happy path.",
+		"4. Keep tests independent — no shared mutable state between tests.",
+		"5. Mock external dependencies; do not hit real network services.",
+	].join("\n"),
+	guardrails: [
+		"Do not skip testing error paths.",
+		"Do not write tests that depend on execution order.",
+		"Do not mock the system under test.",
+	],
+};
+
+const SECURITY_AUDIT_TEMPLATE: SkillTemplate = {
+	id: "security-audit",
+	name: "Security Audit",
+	description: "Security review skill with configurable scope and severity thresholds.",
+	category: "security",
+	variables: [
+		{
+			name: "scope",
+			description: "Audit scope: what parts of the codebase to examine",
+			required: true,
+			options: ["full-codebase", "dependencies", "api-surface", "auth-flows", "input-handling"],
+		},
+		{
+			name: "severityThreshold",
+			description: "Minimum severity to report",
+			required: false,
+			defaultValue: "medium",
+			options: ["low", "medium", "high", "critical"],
+		},
+		{
+			name: "complianceFramework",
+			description: "Compliance framework to check against (if applicable)",
+			required: false,
+			defaultValue: "OWASP Top 10",
+		},
+	],
+	body: [
+		"---",
+		"description: Security audit focusing on {scope} (threshold: {severityThreshold})",
+		"---",
+		"",
+		"# Security Audit Skill",
+		"",
+		"You are a security auditor performing a **{scope}** review.",
+		"",
+		"## Severity Threshold",
+		"",
+		"Report all findings at or above **{severityThreshold}** severity.",
+		"",
+		"## Compliance Framework",
+		"",
+		"Check against: **{complianceFramework}**.",
+		"",
+		"## Methodology",
+		"",
+		"1. Identify the attack surface relevant to the chosen scope.",
+		"2. Trace data flows from untrusted inputs.",
+		"3. Check for common vulnerability classes (injection, auth bypass, etc.).",
+		"4. Verify that secrets/credentials are handled safely.",
+		"5. Document each finding with severity, description, and remediation.",
+	].join("\n"),
+	guardrails: [
+		"Do not ignore low-severity findings that could chain into higher-severity exploits.",
+		"Do not report theoretical issues without evidence in the code.",
+		"Do not store or log real secrets/credentials during the audit.",
+	],
+};
+
+const REFACTOR_TEMPLATE: SkillTemplate = {
+	id: "refactor",
+	name: "Refactor",
+	description: "Refactoring skill with configurable scope and constraints.",
+	category: "maintenance",
+	variables: [
+		{
+			name: "scope",
+			description: "What to refactor: file, module, or architectural pattern",
+			required: true,
+		},
+		{
+			name: "constraints",
+			description: "Constraints to respect during refactoring",
+			required: false,
+			defaultValue: "preserve public API, maintain backward compatibility",
+		},
+		{
+			name: "goal",
+			description: "Primary refactoring goal",
+			required: false,
+			defaultValue: "improve readability and reduce complexity",
+			options: [
+				"improve readability and reduce complexity",
+				"improve performance",
+				"reduce coupling",
+				"enable extensibility",
+				"simplify testability",
+			],
+		},
+	],
+	body: [
+		"---",
+		"description: Refactoring skill targeting {scope}",
+		"---",
+		"",
+		"# Refactor Skill",
+		"",
+		"You are a refactoring specialist working on **{scope}**.",
+		"",
+		"## Goal",
+		"",
+		"Primary objective: **{goal}**.",
+		"",
+		"## Constraints",
+		"",
+		"The following constraints must be respected:",
+		"",
+		"- {constraints}",
+		"",
+		"## Approach",
+		"",
+		"1. Understand the current code structure and all usages.",
+		"2. Plan the refactoring in small, reviewable steps.",
+		"3. Run existing tests after each step to verify correctness.",
+		"4. Add new tests if the refactoring introduces new behavior.",
+		"5. Document any architectural decisions made during the refactor.",
+	].join("\n"),
+	guardrails: [
+		"Do not change public API signatures without explicit approval.",
+		"Do not mix refactoring with feature changes.",
+		"Do not skip running tests between steps.",
+	],
+};
+
+const DOCUMENTATION_TEMPLATE: SkillTemplate = {
+	id: "documentation",
+	name: "Documentation",
+	description: "Documentation writing skill with configurable format and audience.",
+	category: "documentation",
+	variables: [
+		{
+			name: "format",
+			description: "Documentation format to produce",
+			required: true,
+			options: ["markdown", "jsdoc", "rustdoc", "godoc", "pydoc", "openapi"],
+		},
+		{
+			name: "audience",
+			description: "Target audience for the documentation",
+			required: false,
+			defaultValue: "developers",
+			options: ["developers", "operators", "end-users", "contributors", "architects"],
+		},
+		{
+			name: "detailLevel",
+			description: "Level of detail",
+			required: false,
+			defaultValue: "standard",
+			options: ["brief", "standard", "comprehensive"],
+		},
+	],
+	body: [
+		"---",
+		"description: Write {format} documentation for {audience}",
+		"---",
+		"",
+		"# Documentation Skill",
+		"",
+		"You are a technical writer producing **{format}** documentation",
+		"for **{audience}**.",
+		"",
+		"## Detail Level",
+		"",
+		"Detail level: **{detailLevel}**.",
+		"",
+		"## Guidelines",
+		"",
+		"1. Start with a brief summary of what the module/function does.",
+		"2. Document all public APIs with parameter descriptions and return types.",
+		"3. Include usage examples for non-trivial functionality.",
+		"4. Keep language clear and avoid unnecessary jargon.",
+		"5. Cross-reference related modules where applicable.",
+	].join("\n"),
+	guardrails: [
+		"Do not document private/internal APIs unless specifically requested.",
+		"Do not generate placeholder content — every section must be meaningful.",
+		"Do not duplicate information already present in existing docs.",
+	],
+};
+
+const BUILTIN_TEMPLATES: SkillTemplate[] = [
+	CODE_REVIEW_TEMPLATE,
+	TESTING_TEMPLATE,
+	SECURITY_AUDIT_TEMPLATE,
+	REFACTOR_TEMPLATE,
+	DOCUMENTATION_TEMPLATE,
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Return all builtin skill templates.
+ */
+export function getBuiltinTemplates(): SkillTemplate[] {
+	return BUILTIN_TEMPLATES;
+}
+
+/**
+ * Look up a builtin template by its id or name (case-insensitive).
+ */
+export function findTemplate(idOrName: string): SkillTemplate | undefined {
+	const lower = idOrName.toLowerCase();
+	return BUILTIN_TEMPLATES.find((t) => t.id.toLowerCase() === lower || t.name.toLowerCase() === lower);
+}
+
+/**
+ * Instantiate a skill template by filling in its variables.
+ *
+ * - Required variables that are missing throw an error.
+ * - Optional variables fall back to their `defaultValue` if not supplied.
+ * - Variables with `options` constrain the allowed values.
+ *
+ * @param template  The template to instantiate.
+ * @param variables User-supplied variable values.
+ * @returns An object with the suggested filename and rendered content.
+ */
+export function instantiateTemplate(template: SkillTemplate, variables: Record<string, string>): InstantiatedSkill {
+	// Validate and resolve all variable values
+	const resolved: Record<string, string> = {};
+
+	for (const variable of template.variables) {
+		const value = variables[variable.name];
+
+		if (value === undefined || value === "") {
+			if (variable.required) {
+				throw new Error(`Missing required variable "${variable.name}" for template "${template.id}" (${variable.description}).`);
+			}
+			resolved[variable.name] = variable.defaultValue ?? "";
+			continue;
+		}
+
+		// Validate options constraint
+		if (variable.options !== undefined && !variable.options.includes(value)) {
+			throw new Error(
+				`Invalid value "${value}" for variable "${variable.name}" in template "${template.id}". ` +
+					`Allowed values: ${variable.options.join(", ")}.`,
+			);
+		}
+
+		resolved[variable.name] = value;
+	}
+
+	// Render the template body by replacing all {varName} placeholders
+	let content = template.body;
+	for (const [key, value] of Object.entries(resolved)) {
+		// Use a global regex to replace all occurrences of {key}
+		const placeholderRegex = new RegExp(`\\{${escapeRegExp(key)}\\}`, "g");
+		content = content.replace(placeholderRegex, value);
+	}
+
+	// Build filename from template id
+	const filename = `${template.id}.SKILL.md`;
+
+	return { filename, content };
+}
+
+/**
+ * Return a simplified list of available templates suitable for display.
+ * Each entry contains id, name, description, category, and variable names.
+ */
+export function listTemplates(): Array<{
+	id: string;
+	name: string;
+	description: string;
+	category: string;
+	variables: Array<{ name: string; required: boolean }>;
+}> {
+	return BUILTIN_TEMPLATES.map((t) => ({
+		id: t.id,
+		name: t.name,
+		description: t.description,
+		category: t.category,
+		variables: t.variables.map((v) => ({
+			name: v.name,
+			required: v.required,
+		})),
+	}));
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape special regex characters in a string so it can be used inside a
+ * RegExp constructor.
+ */
+function escapeRegExp(input: string): string {
+	return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}