@astrofoundry/pi-astro 0.16.1 → 0.18.1

package/node_modules/pi-subagents/src/agents/skills.ts

@@ -1,630 +0,0 @@
-/**
- * Skill resolution and caching for subagent extension
- */
-
-import { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-export type SkillSource =
-	| "project"
-	| "user"
-	| "project-package"
-	| "user-package"
-	| "project-settings"
-	| "user-settings"
-	| "extension"
-	| "builtin"
-	| "unknown";
-
-interface ResolvedSkill {
-	name: string;
-	path: string;
-	content: string;
-	source: SkillSource;
-}
-
-interface SkillCacheEntry {
-	mtime: number;
-	skill: ResolvedSkill;
-}
-
-interface CachedSkillEntry {
-	name: string;
-	filePath: string;
-	source: SkillSource;
-	description?: string;
-	order: number;
-}
-
-interface SkillSearchPath {
-	path: string;
-	source: SkillSource;
-}
-
-const skillCache = new Map<string, SkillCacheEntry>();
-const MAX_CACHE_SIZE = 50;
-
-let loadSkillsCache: { cwd: string; skills: CachedSkillEntry[]; timestamp: number } | null = null;
-const LOAD_SKILLS_CACHE_TTL_MS = 5000;
-
-const CONFIG_DIR = ".pi";
-const AGENT_DIR = path.join(os.homedir(), ".pi", "agent");
-const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
-
-const SOURCE_PRIORITY: Record<SkillSource, number> = {
-	project: 700,
-	"project-settings": 650,
-	"project-package": 600,
-	user: 300,
-	"user-settings": 250,
-	"user-package": 200,
-	extension: 150,
-	builtin: 100,
-	unknown: 0,
-};
-
-function stripSkillFrontmatter(content: string): string {
-	const normalized = content.replace(/\r\n/g, "\n");
-	if (!normalized.startsWith("---")) return normalized;
-
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) return normalized;
-
-	return normalized.slice(endIndex + 4).trim();
-}
-
-function isWithinPath(filePath: string, dir: string): boolean {
-	const relative = path.relative(dir, filePath);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function readOptionalJsonFile(filePath: string, label: string): unknown {
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-	} catch (error) {
-		const code = typeof error === "object" && error !== null && "code" in error
-			? (error as { code?: unknown }).code
-			: undefined;
-		if (code === "ENOENT") return null;
-		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`Failed to read ${label} '${filePath}': ${message}`, {
-			cause: error instanceof Error ? error : undefined,
-		});
-	}
-}
-
-function readJsonFileBestEffort(filePath: string): unknown {
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-	} catch {
-		// Package scans over installed dependencies are opportunistic.
-		return null;
-	}
-}
-
-function extractSkillPathsFromPackageRoot(packageRoot: string, source: SkillSource, bestEffort = false): SkillSearchPath[] {
-	const packageJsonPath = path.join(packageRoot, "package.json");
-	const pkg = bestEffort
-		? readJsonFileBestEffort(packageJsonPath)
-		: readOptionalJsonFile(packageJsonPath, "package manifest");
-	if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return [];
-	const pi = (pkg as { pi?: unknown }).pi;
-	if (!pi || typeof pi !== "object" || Array.isArray(pi)) return [];
-	const skills = (pi as { skills?: unknown }).skills;
-	if (!Array.isArray(skills)) return [];
-	return skills
-		.filter((entry): entry is string => typeof entry === "string")
-		.map((entry) => ({ path: path.resolve(packageRoot, entry), source }));
-}
-
-let cachedGlobalNpmRoot: string | null = null;
-
-function getGlobalNpmRoot(): string | null {
-	if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
-	try {
-		cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
-		return cachedGlobalNpmRoot;
-	} catch {
-		// Global npm root is optional in constrained environments.
-		cachedGlobalNpmRoot = ""; // Empty string means "tried but failed"
-		return null;
-	}
-}
-
-function collectInstalledPackageSkillPaths(cwd: string): SkillSearchPath[] {
-	const dirs: SkillSearchPath[] = [
-		{ path: path.join(cwd, CONFIG_DIR, "npm", "node_modules"), source: "project-package" },
-		{ path: path.join(AGENT_DIR, "npm", "node_modules"), source: "user-package" },
-	];
-
-	const globalRoot = getGlobalNpmRoot();
-	if (globalRoot) {
-		dirs.push({ path: globalRoot, source: "user-package" });
-	}
-
-	const results: SkillSearchPath[] = [];
-
-	for (const dir of dirs) {
-		if (!fs.existsSync(dir.path)) continue;
-		let entries: fs.Dirent[];
-		try {
-			entries = fs.readdirSync(dir.path, { withFileTypes: true });
-		} catch {
-			continue;
-		}
-
-		for (const entry of entries) {
-			if (entry.name.startsWith(".")) continue;
-			if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-
-			if (entry.name.startsWith("@")) {
-				const scopeDir = path.join(dir.path, entry.name);
-				let scopeEntries: fs.Dirent[];
-				try {
-					scopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
-				} catch {
-					continue;
-				}
-				for (const scopeEntry of scopeEntries) {
-					if (scopeEntry.name.startsWith(".")) continue;
-					if (!scopeEntry.isDirectory() && !scopeEntry.isSymbolicLink()) continue;
-					const pkgRoot = path.join(scopeDir, scopeEntry.name);
-					results.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));
-				}
-				continue;
-			}
-
-			const pkgRoot = path.join(dir.path, entry.name);
-			results.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));
-		}
-	}
-
-	return results;
-}
-
-function collectSettingsSkillPaths(cwd: string): SkillSearchPath[] {
-	const results: SkillSearchPath[] = [];
-	const settingsFiles = [
-		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-settings" as const },
-		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR, source: "user-settings" as const },
-	];
-
-	for (const { file, base, source } of settingsFiles) {
-		const settings = readOptionalJsonFile(file, "skills settings file");
-		if (!settings || typeof settings !== "object" || Array.isArray(settings)) continue;
-		const skills = (settings as { skills?: unknown }).skills;
-		if (!Array.isArray(skills)) continue;
-		for (const entry of skills) {
-			if (typeof entry !== "string") continue;
-			let resolved = entry;
-			if (resolved.startsWith("~/")) {
-				resolved = path.join(os.homedir(), resolved.slice(2));
-			} else if (!path.isAbsolute(resolved)) {
-				resolved = path.resolve(base, resolved);
-			}
-			results.push({ path: resolved, source });
-		}
-	}
-
-	return results;
-}
-
-function isSafePackagePath(value: string): boolean {
-	return value.length > 0
-		&& !path.isAbsolute(value)
-		&& value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
-}
-
-function parseNpmPackageName(source: string): string | undefined {
-	const spec = source.slice(4).trim();
-	if (!spec) return undefined;
-	const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
-	const packageName = match?.[1] ?? spec;
-	return isSafePackagePath(packageName) ? packageName : undefined;
-}
-
-function stripGitRef(repoPath: string): string {
-	const atIndex = repoPath.indexOf("@");
-	const hashIndex = repoPath.indexOf("#");
-	const refIndex = [atIndex, hashIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];
-	return refIndex === undefined ? repoPath : repoPath.slice(0, refIndex);
-}
-
-function parseGitPackagePath(source: string): { host: string; repoPath: string } | undefined {
-	const spec = source.slice(4).trim();
-	if (!spec) return undefined;
-
-	let host = "";
-	let repoPath = "";
-	const scpLike = spec.match(/^git@([^:]+):(.+)$/);
-	if (scpLike) {
-		host = scpLike[1] ?? "";
-		repoPath = scpLike[2] ?? "";
-	} else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec)) {
-		try {
-			const url = new URL(spec);
-			host = url.hostname;
-			repoPath = url.pathname.replace(/^\/+/, "");
-		} catch {
-			return undefined;
-		}
-	} else {
-		const slashIndex = spec.indexOf("/");
-		if (slashIndex < 0) return undefined;
-		host = spec.slice(0, slashIndex);
-		repoPath = spec.slice(slashIndex + 1);
-	}
-
-	const normalizedPath = stripGitRef(repoPath).replace(/\.git$/, "").replace(/^\/+/, "");
-	if (!host || !isSafePackagePath(host) || !isSafePackagePath(normalizedPath) || normalizedPath.split(/[\\/]/).length < 2) {
-		return undefined;
-	}
-	return { host, repoPath: normalizedPath };
-}
-
-function resolveSettingsPackageRoot(source: string, baseDir: string): string | undefined {
-	const trimmed = source.trim();
-	if (!trimmed) return undefined;
-	if (trimmed.startsWith("git:")) {
-		const parsed = parseGitPackagePath(trimmed);
-		return parsed ? path.join(baseDir, "git", parsed.host, parsed.repoPath) : undefined;
-	}
-	if (trimmed.startsWith("npm:")) {
-		const packageName = parseNpmPackageName(trimmed);
-		return packageName ? path.join(baseDir, "npm", "node_modules", packageName) : undefined;
-	}
-	const normalized = trimmed.startsWith("file:") ? trimmed.slice(5) : trimmed;
-	if (normalized === "~") return os.homedir();
-	if (normalized.startsWith("~/")) return path.join(os.homedir(), normalized.slice(2));
-	if (path.isAbsolute(normalized)) return normalized;
-	if (normalized === "." || normalized === ".." || normalized.startsWith("./") || normalized.startsWith("../")) {
-		return path.resolve(baseDir, normalized);
-	}
-	return undefined;
-}
-
-function collectSettingsPackageSkillPaths(cwd: string): SkillSearchPath[] {
-	const settingsFiles = [
-		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-package" as const },
-		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR, source: "user-package" as const },
-	];
-	const results: SkillSearchPath[] = [];
-
-	for (const { file, base, source } of settingsFiles) {
-		const settings = readOptionalJsonFile(file, "skills settings file");
-		if (!settings || typeof settings !== "object" || Array.isArray(settings)) continue;
-		const packages = (settings as { packages?: unknown }).packages;
-		if (!Array.isArray(packages)) continue;
-
-		for (const entry of packages) {
-			const packageSource = typeof entry === "string"
-				? entry
-				: typeof entry === "object" && entry !== null && typeof (entry as { source?: unknown }).source === "string"
-					? (entry as { source: string }).source
-					: undefined;
-			if (!packageSource) continue;
-
-			const packageRoot = resolveSettingsPackageRoot(packageSource, base);
-			if (!packageRoot) continue;
-			results.push(...extractSkillPathsFromPackageRoot(packageRoot, source));
-		}
-	}
-
-	return results;
-}
-
-function buildSkillPaths(cwd: string): SkillSearchPath[] {
-	const skillPaths: SkillSearchPath[] = [
-		{ path: path.join(cwd, CONFIG_DIR, "skills"), source: "project" },
-		{ path: path.join(cwd, ".agents", "skills"), source: "project" },
-		{ path: path.join(AGENT_DIR, "skills"), source: "user" },
-		{ path: path.join(os.homedir(), ".agents", "skills"), source: "user" },
-		...collectInstalledPackageSkillPaths(cwd),
-		...collectSettingsPackageSkillPaths(cwd),
-		...extractSkillPathsFromPackageRoot(cwd, "project-package"),
-		...collectSettingsSkillPaths(cwd),
-	];
-
-	const deduped = new Map<string, SkillSearchPath>();
-	for (const entry of skillPaths) {
-		const resolvedPath = path.resolve(entry.path);
-		if (!deduped.has(resolvedPath)) {
-			deduped.set(resolvedPath, { path: resolvedPath, source: entry.source });
-		}
-	}
-	return [...deduped.values()];
-}
-
-function inferSkillSource(filePath: string, cwd: string, sourceHint?: SkillSource): SkillSource {
-	if (sourceHint) return sourceHint;
-
-	const projectConfigRoot = path.resolve(cwd, CONFIG_DIR);
-	const projectSkillsRoot = path.resolve(cwd, CONFIG_DIR, "skills");
-	const projectPackagesRoot = path.resolve(cwd, CONFIG_DIR, "npm", "node_modules");
-	const projectAgentsRoot = path.resolve(cwd, ".agents");
-	const userSkillsRoot = path.resolve(AGENT_DIR, "skills");
-	const userPackagesRoot = path.resolve(AGENT_DIR, "npm", "node_modules");
-	const userAgentsRoot = path.resolve(os.homedir(), ".agents");
-
-	if (isWithinPath(filePath, projectPackagesRoot)) return "project-package";
-	if (isWithinPath(filePath, projectSkillsRoot) || isWithinPath(filePath, projectAgentsRoot)) return "project";
-	if (isWithinPath(filePath, projectConfigRoot)) return "project-settings";
-
-	if (isWithinPath(filePath, userPackagesRoot)) return "user-package";
-	if (isWithinPath(filePath, userSkillsRoot) || isWithinPath(filePath, userAgentsRoot)) return "user";
-	if (isWithinPath(filePath, AGENT_DIR)) return "user-settings";
-
-	const globalRoot = getGlobalNpmRoot();
-	if (globalRoot && isWithinPath(filePath, globalRoot)) return "user-package";
-
-	return "unknown";
-}
-
-function chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candidate: CachedSkillEntry): CachedSkillEntry {
-	if (!existing) return candidate;
-	const existingPriority = SOURCE_PRIORITY[existing.source] ?? 0;
-	const candidatePriority = SOURCE_PRIORITY[candidate.source] ?? 0;
-	if (candidatePriority > existingPriority) return candidate;
-	if (candidatePriority < existingPriority) return existing;
-	return candidate.order < existing.order ? candidate : existing;
-}
-
-function maybeReadSkillDescription(filePath: string): string | undefined {
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		const normalized = content.replace(/\r\n/g, "\n");
-		if (!normalized.startsWith("---")) return undefined;
-
-		const endIndex = normalized.indexOf("\n---", 3);
-		if (endIndex === -1) return undefined;
-
-		const frontmatter = normalized.slice(3, endIndex).trim();
-		const match = frontmatter.match(/^description:\s*(.+)$/m);
-		if (!match) return undefined;
-		return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
-	} catch {
-		// Description parsing is best-effort metadata extraction.
-		return undefined;
-	}
-}
-
-function collectFilesystemSkills(cwd: string, skillPaths: SkillSearchPath[]): CachedSkillEntry[] {
-	const entries: CachedSkillEntry[] = [];
-	const seen = new Set<string>();
-	let order = 0;
-
-	const pushEntry = (name: string, filePath: string, sourceHint?: SkillSource) => {
-		const resolvedFile = path.resolve(filePath);
-		if (seen.has(resolvedFile)) return;
-		if (!fs.existsSync(resolvedFile)) return;
-		seen.add(resolvedFile);
-		entries.push({
-			name,
-			filePath: resolvedFile,
-			source: inferSkillSource(resolvedFile, cwd, sourceHint),
-			description: maybeReadSkillDescription(resolvedFile),
-			order: order++,
-		});
-	};
-
-	for (const skillPath of skillPaths) {
-		if (!fs.existsSync(skillPath.path)) continue;
-
-		let stat: fs.Stats;
-		try {
-			stat = fs.statSync(skillPath.path);
-		} catch {
-			continue;
-		}
-
-		if (stat.isFile()) {
-			const fileName = path.basename(skillPath.path);
-			if (!fileName.toLowerCase().endsWith(".md")) continue;
-			const skillName = fileName.toLowerCase() === "skill.md"
-				? path.basename(path.dirname(skillPath.path))
-				: path.basename(fileName, path.extname(fileName));
-			pushEntry(skillName, skillPath.path, skillPath.source);
-			continue;
-		}
-
-		if (!stat.isDirectory()) continue;
-
-		const rootSkillFile = path.join(skillPath.path, "SKILL.md");
-		if (fs.existsSync(rootSkillFile)) {
-			pushEntry(path.basename(skillPath.path), rootSkillFile, skillPath.source);
-		}
-
-		let childEntries: fs.Dirent[];
-		try {
-			childEntries = fs.readdirSync(skillPath.path, { withFileTypes: true });
-		} catch {
-			continue;
-		}
-
-		for (const child of childEntries) {
-			if (child.name.startsWith(".")) continue;
-			const childPath = path.join(skillPath.path, child.name);
-			if (child.isDirectory() || child.isSymbolicLink()) {
-				const nestedSkillPath = path.join(childPath, "SKILL.md");
-				if (fs.existsSync(nestedSkillPath)) {
-					pushEntry(child.name, nestedSkillPath, skillPath.source);
-				}
-				continue;
-			}
-			if (child.isFile() && child.name.toLowerCase().endsWith(".md")) {
-				pushEntry(path.basename(child.name, path.extname(child.name)), childPath, skillPath.source);
-			}
-		}
-	}
-
-	return entries;
-}
-
-function getCachedSkills(cwd: string): CachedSkillEntry[] {
-	const now = Date.now();
-	if (loadSkillsCache && loadSkillsCache.cwd === cwd && now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS) {
-		return loadSkillsCache.skills;
-	}
-
-	const skillPaths = buildSkillPaths(cwd);
-	const loaded = collectFilesystemSkills(cwd, skillPaths);
-	const dedupedByName = new Map<string, CachedSkillEntry>();
-
-	for (const entry of loaded) {
-		const current = dedupedByName.get(entry.name);
-		dedupedByName.set(entry.name, chooseHigherPrioritySkill(current, entry));
-	}
-
-	const skills = [...dedupedByName.values()].sort((a, b) => a.order - b.order);
-	loadSkillsCache = { cwd, skills, timestamp: now };
-	return skills;
-}
-
-export function resolveSkillPath(
-	skillName: string,
-	cwd: string,
-): { path: string; source: SkillSource } | undefined {
-	const skills = getCachedSkills(cwd);
-	const skill = skills.find((s) => s.name === skillName);
-	if (!skill) return undefined;
-	return { path: skill.filePath, source: skill.source };
-}
-
-function readSkill(
-	skillName: string,
-	skillPath: string,
-	source: SkillSource,
-): ResolvedSkill | undefined {
-	try {
-		const stat = fs.statSync(skillPath);
-		const cached = skillCache.get(skillPath);
-		if (cached && cached.mtime === stat.mtimeMs) {
-			return cached.skill;
-		}
-
-		const raw = fs.readFileSync(skillPath, "utf-8");
-		const content = stripSkillFrontmatter(raw);
-		const skill: ResolvedSkill = {
-			name: skillName,
-			path: skillPath,
-			content,
-			source,
-		};
-
-		skillCache.set(skillPath, { mtime: stat.mtimeMs, skill });
-		if (skillCache.size > MAX_CACHE_SIZE) {
-			const firstKey = skillCache.keys().next().value;
-			if (firstKey) skillCache.delete(firstKey);
-		}
-
-		return skill;
-	} catch {
-		// Treat unreadable skill files as unresolved so callers can surface as missing.
-		return undefined;
-	}
-}
-
-export function resolveSkills(
-	skillNames: string[],
-	cwd: string,
-): { resolved: ResolvedSkill[]; missing: string[] } {
-	const resolved: ResolvedSkill[] = [];
-	const missing: string[] = [];
-
-	for (const name of skillNames) {
-		const trimmed = name.trim();
-		if (!trimmed) continue;
-		if (trimmed === SUBAGENT_ORCHESTRATION_SKILL) {
-			missing.push(trimmed);
-			continue;
-		}
-
-		const location = resolveSkillPath(trimmed, cwd);
-		if (!location) {
-			missing.push(trimmed);
-			continue;
-		}
-
-		const skill = readSkill(trimmed, location.path, location.source);
-		if (skill) {
-			resolved.push(skill);
-		} else {
-			missing.push(trimmed);
-		}
-	}
-
-	return { resolved, missing };
-}
-
-export function resolveSkillsWithFallback(
-	skillNames: string[],
-	primaryCwd: string,
-	fallbackCwd?: string,
-): { resolved: ResolvedSkill[]; missing: string[] } {
-	const primary = resolveSkills(skillNames, primaryCwd);
-	if (!fallbackCwd || primary.missing.length === 0) return primary;
-	if (path.resolve(primaryCwd) === path.resolve(fallbackCwd)) return primary;
-
-	const fallback = resolveSkills(primary.missing, fallbackCwd);
-	return {
-		resolved: [...primary.resolved, ...fallback.resolved],
-		missing: fallback.missing,
-	};
-}
-
-export function buildSkillInjection(skills: ResolvedSkill[]): string {
-	if (skills.length === 0) return "";
-
-	return skills
-		.map((s) => `<skill name="${s.name}">\n${s.content}\n</skill>`)
-		.join("\n\n");
-}
-
-export function normalizeSkillInput(
-	input: string | string[] | boolean | undefined,
-): string[] | false | undefined {
-	if (input === false) return false;
-	if (input === true || input === undefined) return undefined;
-	if (Array.isArray(input)) {
-		return [...new Set(input.map((s) => s.trim()).filter((s) => s.length > 0))];
-	}
-	// Guard against JSON-encoded arrays arriving as strings (e.g. '["a","b"]').
-	// Models sometimes serialise the skill parameter as a JSON string instead of
-	// a native array, and naively splitting on "," would embed brackets/quotes
-	// into the skill names, causing resolution to silently fail.
-	const trimmed = input.trim();
-	if (trimmed.startsWith("[")) {
-		try {
-			const parsed = JSON.parse(trimmed);
-			if (Array.isArray(parsed)) {
-				return normalizeSkillInput(parsed);
-			}
-		} catch {
-			// Not valid JSON – fall through to comma-split
-		}
-	}
-	return [...new Set(input.split(",").map((s) => s.trim()).filter((s) => s.length > 0))];
-}
-
-export function discoverAvailableSkills(cwd: string): Array<{
-	name: string;
-	source: SkillSource;
-	description?: string;
-}> {
-	const skills = getCachedSkills(cwd);
-	return skills
-		.filter((s) => s.name !== SUBAGENT_ORCHESTRATION_SKILL)
-		.map((s) => ({
-			name: s.name,
-			source: s.source,
-			description: s.description,
-		}))
-		.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-export function clearSkillCache(): void {
-	skillCache.clear();
-	loadSkillsCache = null;
-}