agent-skills-standard 2.4.8 → 2.5.1

package/README.md

@@ -5,7 +5,7 @@
 
 **Sync 242 AI coding standards to any project in one command.** Works with Cursor, Claude Code, GitHub Copilot, Gemini, Windsurf, Trae, Kiro, and Roo.
 
-**Current release:** `v2.4.7` — workflow-end telemetry guidance, MCP session-cost helpers, and clearer runtime integration for SDLC handoff reporting.
+**Current release:** `v2.5.1` — automated SkillSpector security scanning, pull request evaluation gates, and verified release tags.
 
 ```bash
 npx agent-skills-standard@latest init   # detect your stack

package/dist/index.js

@@ -43,7 +43,7 @@ let child_process = require("child_process");
 let fs = require("fs");
 var package_default = {
 	name: "agent-skills-standard",
-	version: "2.4.8",
+	version: "2.5.1",
 	description: "A CLI to manage and sync AI agent skills standard for Cursor, Claude, Copilot, Windsurf, and more.",
 	main: "dist/index.js",
 	bin: {
@@ -83,7 +83,7 @@ var package_default = {
 		"dotenv": "^17.2.3",
 		"fs-extra": "^11.2.0",
 		"inquirer": "^8.2.5",
-		"js-yaml": "^4.1.0",
+		"js-yaml": "^4.2.0",
 		"picocolors": "^1.0.0",
 		"zod": "^3.22.4"
 	},
@@ -342,6 +342,7 @@ var Framework = /* @__PURE__ */ function(Framework) {
 	Framework["Android"] = "android";
 	Framework["iOS"] = "ios";
 	Framework["Laravel"] = "laravel";
+	Framework["Python"] = "python";
 	return Framework;
 }({});
 //#endregion
@@ -672,7 +673,8 @@ var BACKEND_FRAMEWORKS = [
 	Framework.NestJS,
 	Framework.Golang,
 	Framework.SpringBoot,
-	Framework.Laravel
+	Framework.Laravel,
+	Framework.Python
 ];
 var FRONTEND_FRAMEWORKS = [
 	Framework.React,
@@ -1007,6 +1009,20 @@ var getFrameworkDefinition = (id) => {
 				javascript: ["resources/js", "vite.config.js"]
 			}
 		};
+		case Framework.Python: return {
+			id,
+			name: "Python",
+			languages: ["python"],
+			detectionFiles: [
+				"pyproject.toml",
+				"requirements.txt",
+				"setup.py",
+				"setup.cfg",
+				"Pipfile",
+				"poetry.lock",
+				"uv.lock"
+			]
+		};
 	}
 };
 var SUPPORTED_AGENTS = Object.values(Agent).map(getAgentDefinition);
@@ -1042,11 +1058,181 @@ var SkillConfigSchema = zod.z.object({
 	mcp: McpConfigSchema.optional()
 });
 var DEFAULT_SDLC_SUPPORT_CATEGORIES = ["quality-engineering"];
+var PRIMARY_CONFIG_FILE = ".skillsrc";
+var LEGACY_YAML_CONFIG_FILE = ".skillsrc.yaml";
 /**
 * Service for managing the `.skillsrc` configuration file.
 * Handles loading, saving, and initial construction of the configuration based on project metadata.
 */
 var ConfigService = class {
+	getPrimaryConfigPath(cwd) {
+		return path.default.join(cwd, PRIMARY_CONFIG_FILE);
+	}
+	getLegacyYamlConfigPath(cwd) {
+		return path.default.join(cwd, LEGACY_YAML_CONFIG_FILE);
+	}
+	async resolveConfigPath(cwd) {
+		const primaryPath = this.getPrimaryConfigPath(cwd);
+		if (await fs_extra.default.pathExists(primaryPath)) return primaryPath;
+		const legacyYamlPath = this.getLegacyYamlConfigPath(cwd);
+		if (await fs_extra.default.pathExists(legacyYamlPath)) return legacyYamlPath;
+		return null;
+	}
+	dumpConfig(config) {
+		return js_yaml.default.dump(config, {
+			noRefs: true,
+			lineWidth: -1
+		});
+	}
+	isRecord(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+	stripAngleBrackets(value) {
+		const trimmed = value.trim();
+		if (trimmed.startsWith("<") && trimmed.endsWith(">")) return trimmed.slice(1, -1).trim();
+		return trimmed;
+	}
+	parseLegacyList(value) {
+		const trimmed = value.trim();
+		if (!trimmed || trimmed === "[]") return [];
+		if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed.slice(1, -1).split(",").map((item) => item.trim()).filter(Boolean);
+		if (trimmed.startsWith("- ")) return trimmed.replace(/^-\s+/, "").split(/\s+-\s+/).map((item) => item.trim()).filter(Boolean);
+		return trimmed.split(",").map((item) => item.trim()).filter(Boolean);
+	}
+	parseLegacyBoolean(value) {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") return true;
+		if (normalized === "false") return false;
+	}
+	migrateLegacyTextConfig(content) {
+		const lines = content.split(/\r?\n/);
+		const registryLine = lines.find((line) => line.trim().startsWith("registry:"));
+		const agentsIndex = lines.findIndex((line) => line.trim() === "agents:");
+		const skillsIndex = lines.findIndex((line) => line.trim() === "skills:");
+		if (!registryLine || agentsIndex === -1 || skillsIndex === -1) return null;
+		const registryMatch = registryLine.match(/^\s*registry:\s*(.+)$/);
+		if (!registryMatch) return null;
+		const config = {
+			registry: this.stripAngleBrackets(registryMatch[1]),
+			agents: [],
+			skills: {}
+		};
+		const agents = [];
+		for (let index = agentsIndex + 1; index < skillsIndex; index += 1) {
+			const match = lines[index].match(/^\s*-\s+(.+)$/);
+			if (!match) continue;
+			agents.push(match[1].trim());
+		}
+		config.agents = agents;
+		const sectionNames = new Set([
+			"custom_overrides",
+			"workflows",
+			"mcp"
+		]);
+		let currentCategory = null;
+		for (let index = skillsIndex + 1; index < lines.length; index += 1) {
+			const trimmed = lines[index].trim();
+			if (!trimmed) continue;
+			if (trimmed === "workflows:" || trimmed === "mcp:" || trimmed.startsWith("custom_overrides:")) break;
+			const categoryMatch = trimmed.match(/^([A-Za-z0-9-]+):$/);
+			if (categoryMatch && !sectionNames.has(categoryMatch[1])) {
+				currentCategory = categoryMatch[1];
+				config.skills[currentCategory] = {};
+				continue;
+			}
+			if (!currentCategory) continue;
+			const refMatch = trimmed.match(/^ref:\s*(.+)$/);
+			if (refMatch) {
+				config.skills[currentCategory].ref = refMatch[1].trim();
+				continue;
+			}
+			const excludeMatch = trimmed.match(/^exclude:\s*(.+)$/);
+			if (excludeMatch) {
+				config.skills[currentCategory].exclude = this.parseLegacyList(excludeMatch[1]);
+				continue;
+			}
+			const includeMatch = trimmed.match(/^include:\s*(.+)$/);
+			if (includeMatch) config.skills[currentCategory].include = this.parseLegacyList(includeMatch[1]);
+		}
+		const overridesLine = lines.find((line) => line.trim().startsWith("custom_overrides:"));
+		if (overridesLine) {
+			const match = overridesLine.match(/^\s*custom_overrides:\s*(.*)$/);
+			config.custom_overrides = this.parseLegacyList(match?.[1] ?? "");
+		}
+		const workflowsIndex = lines.findIndex((line) => line.trim() === "workflows:");
+		if (workflowsIndex !== -1) {
+			const workflows = [];
+			for (let index = workflowsIndex + 1; index < lines.length; index += 1) {
+				const trimmed = lines[index].trim();
+				if (!trimmed) continue;
+				if (trimmed === "mcp:") break;
+				const match = trimmed.match(/^-\s+(.+)$/);
+				if (match) workflows.push(match[1].trim());
+			}
+			config.workflows = workflows;
+		}
+		const mcpIndex = lines.findIndex((line) => line.trim() === "mcp:");
+		if (mcpIndex !== -1) {
+			const mcp = {};
+			for (let index = mcpIndex + 1; index < lines.length; index += 1) {
+				const trimmed = lines[index].trim();
+				if (!trimmed) continue;
+				const match = trimmed.match(/^([A-Za-z0-9_]+):\s*(.+)$/);
+				if (!match) continue;
+				const [, key, rawValue] = match;
+				if (key === "enabled" || key === "prompted" || key === "snippets") mcp[key] = this.parseLegacyBoolean(rawValue);
+				else mcp[key] = rawValue.trim();
+			}
+			config.mcp = mcp;
+		}
+		return config;
+	}
+	normalizeRawConfig(rawConfig) {
+		if (!this.isRecord(rawConfig)) return {
+			config: {},
+			migrated: false
+		};
+		const normalized = { ...rawConfig };
+		let migrated = false;
+		if (typeof normalized.registry === "string") {
+			const strippedRegistry = this.stripAngleBrackets(normalized.registry);
+			if (strippedRegistry !== normalized.registry) {
+				normalized.registry = strippedRegistry;
+				migrated = true;
+			}
+		}
+		if (Array.isArray(normalized.agents)) normalized.agents = normalized.agents.map((agent) => {
+			if (typeof agent === "string" && agent.toLowerCase() === "openai") {
+				migrated = true;
+				return Agent.Codex;
+			}
+			return agent;
+		});
+		if (this.isRecord(normalized.skills)) {
+			const normalizedSkills = {};
+			for (const [category, value] of Object.entries(normalized.skills)) {
+				if (!this.isRecord(value)) {
+					normalizedSkills[category] = {};
+					migrated = true;
+					continue;
+				}
+				const entry = {};
+				if (typeof value.ref === "string") entry.ref = value.ref;
+				if (Array.isArray(value.include)) entry.include = value.include.filter((item) => typeof item === "string");
+				if (Array.isArray(value.exclude)) entry.exclude = value.exclude.filter((item) => typeof item === "string");
+				else if (typeof value.exclude === "string") {
+					entry.exclude = this.parseLegacyList(value.exclude);
+					migrated = true;
+				}
+				normalizedSkills[category] = entry;
+			}
+			normalized.skills = normalizedSkills;
+		}
+		return {
+			config: normalized,
+			migrated
+		};
+	}
 	getCategoryRef(category, metadata) {
 		const categoryMetadata = metadata.categories?.[category];
 		if (!categoryMetadata?.version) return "main";
@@ -1059,27 +1245,26 @@ var ConfigService = class {
 	* @throws Error if the configuration format is invalid
 	*/
 	async loadConfig(cwd = process.cwd()) {
-		const configPath = path.default.join(cwd, ".skillsrc");
-		if (!await fs_extra.default.pathExists(configPath)) return null;
+		const configPath = await this.resolveConfigPath(cwd);
+		if (!configPath) return null;
+		const primaryConfigPath = this.getPrimaryConfigPath(cwd);
+		const shouldRenameLegacyYamlFile = configPath !== primaryConfigPath;
 		try {
 			const content = await fs_extra.default.readFile(configPath, "utf8");
-			const rawConfig = js_yaml.default.load(content);
-			if (rawConfig && Array.isArray(rawConfig.agents)) {
-				let needsMigration = false;
-				const updatedAgents = rawConfig.agents.map((agent) => {
-					if (typeof agent === "string" && agent.toLowerCase() === "openai") {
-						needsMigration = true;
-						return Agent.Codex;
-					}
-					return agent;
-				});
-				if (needsMigration) {
-					rawConfig.agents = updatedAgents;
-					await fs_extra.default.outputFile(configPath, js_yaml.default.dump(rawConfig));
-				}
+			let rawConfig;
+			let migratedFromText = false;
+			try {
+				rawConfig = js_yaml.default.load(content);
+			} catch (parseError) {
+				rawConfig = this.migrateLegacyTextConfig(content);
+				migratedFromText = rawConfig !== null;
+				if (!migratedFromText) throw parseError;
 			}
-			const parsed = SkillConfigSchema.safeParse(rawConfig);
+			const { config: normalizedConfig, migrated } = this.normalizeRawConfig(rawConfig);
+			const parsed = SkillConfigSchema.safeParse(normalizedConfig);
 			if (!parsed.success) throw new Error(`Invalid .skillsrc format: ${parsed.error.message}`);
+			if (migratedFromText || migrated || shouldRenameLegacyYamlFile) await fs_extra.default.outputFile(primaryConfigPath, this.dumpConfig(parsed.data));
+			if (shouldRenameLegacyYamlFile) await fs_extra.default.remove(configPath);
 			return parsed.data;
 		} catch (error) {
 			throw new Error(`Failed to load config: ${error}`);
@@ -1091,8 +1276,10 @@ var ConfigService = class {
 	* @param cwd Current working directory
 	*/
 	async saveConfig(config, cwd = process.cwd()) {
-		const configPath = path.default.join(cwd, ".skillsrc");
-		await fs_extra.default.outputFile(configPath, js_yaml.default.dump(config));
+		const primaryConfigPath = this.getPrimaryConfigPath(cwd);
+		const legacyYamlPath = this.getLegacyYamlConfigPath(cwd);
+		await fs_extra.default.outputFile(primaryConfigPath, this.dumpConfig(config));
+		if (legacyYamlPath !== primaryConfigPath && await fs_extra.default.pathExists(legacyYamlPath)) await fs_extra.default.remove(legacyYamlPath);
 	}
 	/**
 	* Constructs an initial configuration object based on project analysis.
@@ -1289,7 +1476,9 @@ process.stdin.on('end', () => {
       '[SKILL TRIGGER] Editing: ' + fileName + '\\n' +
       '-> Call load_skills_for_files(files=[ "' + filePath + '" ]) on the ' +
       'agent-skills-standard MCP. It returns applicable SKILL.md rules, ' +
-      'or nothing if no skills match this file type.'
+      'or nothing if no skills match this file type.\\n' +
+      '-> If this work spans a whole framework or migration, also call ' +
+      'get_category_guide(category="...") for the framework-level map.'
     );
     process.exit(0);
   } catch {
@@ -4188,25 +4377,35 @@ var MarkdownUtils = class {
 	* @param rootDir Project root directory
 	* @param targets Array of target file names
 	* @param indexContent The markdown content to inject
+	* @returns Array of target files that were successfully updated/created
 	*/
 	static async injectIndex(rootDir, targets, indexContent) {
+		const updated = [];
 		for (const target of targets) {
 			const targetPath = path.default.join(rootDir, target);
 			let content = "";
+			const markerStart = "<!-- SKILLS_INDEX_START -->";
+			const markerEnd = "<!-- SKILLS_INDEX_END -->";
 			if (await fs_extra.default.pathExists(targetPath)) {
 				content = await fs_extra.default.readFile(targetPath, "utf8");
-				const markerStart = "<!-- SKILLS_INDEX_START -->";
-				const markerEnd = "<!-- SKILLS_INDEX_END -->";
 				const startIndex = content.indexOf(markerStart);
 				const endIndex = content.indexOf(markerEnd);
 				if (startIndex !== -1 && endIndex !== -1 && startIndex < endIndex) content = `${content.substring(0, startIndex + 27)}\n${indexContent}\n${content.substring(endIndex)}`;
-				else if (startIndex !== -1 || endIndex !== -1) {
-					content = content.replace(markerStart, "").replace(markerEnd, "");
-					content = content.trimEnd() + `\n\n${markerStart}\n${indexContent}\n${markerEnd}\n`;
-				} else content = content.trimEnd() + `\n\n${markerStart}\n${indexContent}\n${markerEnd}\n`;
-			} else content = `<!-- SKILLS_INDEX_START -->\n${indexContent}\n<!-- SKILLS_INDEX_END -->\n`;
+				else continue;
+			} else content = [
+				"# Project Context for AI Agents",
+				"",
+				"This file provides context and instructions for AI agents working in this repository.",
+				"",
+				markerStart,
+				indexContent,
+				markerEnd,
+				""
+			].join("\n");
 			await fs_extra.default.outputFile(targetPath, content);
+			updated.push(target);
 		}
+		return updated;
 	}
 };
 //#endregion
@@ -4302,13 +4501,11 @@ var SyncService = class {
 			if (Object.keys(categoryIndices).length > 0) console.log(picocolors.default.green(`  ✅ Generated _INDEX.md for ${Object.keys(categoryIndices).length} categories.`));
 			const mcpEnabled = config.mcp?.enabled === true;
 			const routerIndex = await generator.assembleRouterIndex(baseDir, allowedCategories, mcpEnabled);
-			await MarkdownUtils.injectIndex(process.cwd(), ["AGENTS.md"], routerIndex);
-			console.log(picocolors.default.green("  ✅ AGENTS.md router index updated."));
+			if ((await MarkdownUtils.injectIndex(process.cwd(), ["AGENTS.md"], routerIndex)).length > 0) console.log(picocolors.default.green("  ✅ AGENTS.md router index updated."));
+			else console.log(picocolors.default.yellow("  ⚠️  Skipped AGENTS.md update: index markers <!-- SKILLS_INDEX_START --> … <!-- SKILLS_INDEX_END --> are missing or out of order. Opt-in by adding these markers to your file."));
 			const serverDir = path.default.join(process.cwd(), "server");
-			if (await fs_extra.default.pathExists(serverDir)) {
-				await MarkdownUtils.injectIndex(serverDir, ["AGENTS.md"], routerIndex);
-				console.log(picocolors.default.green("  ✅ server/AGENTS.md router index updated."));
-			}
+			if (await fs_extra.default.pathExists(serverDir)) if ((await MarkdownUtils.injectIndex(serverDir, ["AGENTS.md"], routerIndex)).length > 0) console.log(picocolors.default.green("  ✅ server/AGENTS.md router index updated."));
+			else console.log(picocolors.default.yellow("  ⚠️  Skipped server/AGENTS.md update: index markers <!-- SKILLS_INDEX_START --> … <!-- SKILLS_INDEX_END --> are missing or out of order in server/AGENTS.md. Opt-in via markers."));
 			await new AgentBridgeService().bridge(process.cwd(), agents);
 		} catch (error) {
 			console.log(picocolors.default.yellow(`  ⚠️  Failed to update index: ${error}`));