@agentyx/core 0.2.0 → 0.3.1

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { access, readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 //#region src/errors.ts
 /**
 * Base class for every failure Agentyx raises deliberately.
@@ -20,6 +21,27 @@ var AgentyxError = class extends Error {
 	}
 };
 //#endregion
+//#region src/issues.ts
+/**
+* Turns a Zod failure into locations a reader can find in the file.
+*
+* Shared by every document Agentyx validates, so a problem in `.agentyx.json`
+* and a problem in `.agentyx.lock.json` are reported the same way.
+*/
+function toAgentyxIssues(error) {
+	return error.issues.map((issue) => ({
+		path: formatIssuePath(issue.path),
+		message: issue.message
+	}));
+}
+function formatIssuePath(path) {
+	if (path.length === 0) return "(root)";
+	return path.reduce((formatted, segment) => {
+		if (typeof segment === "number") return `${formatted}[${segment}]`;
+		return formatted === "" ? String(segment) : `${formatted}.${String(segment)}`;
+	}, "");
+}
+//#endregion
 //#region src/config/errors.ts
 /** Raised when the supplied directory has no `.agentyx.json`. */
 var AgentyxConfigNotFoundError = class extends AgentyxError {
@@ -45,7 +67,7 @@ var AgentyxConfigValidationError = class extends AgentyxError {
 	/** The file the configuration came from, when it was read from disk. */
 	filePath;
 	constructor(error, filePath) {
-		const issues = toConfigIssues(error);
+		const issues = toAgentyxIssues(error);
 		const location = filePath === void 0 ? "" : ` in ${filePath}`;
 		const details = issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n");
 		super("agentyx_config_invalid", `Invalid Agentyx configuration${location}:\n${details}`);
@@ -65,19 +87,6 @@ var UnknownEnabledCapabilityError = class extends AgentyxError {
 		this.knownCapabilities = knownCapabilities;
 	}
 };
-function toConfigIssues(error) {
-	return error.issues.map((issue) => ({
-		path: formatIssuePath(issue.path),
-		message: issue.message
-	}));
-}
-function formatIssuePath(path) {
-	if (path.length === 0) return "(root)";
-	return path.reduce((formatted, segment) => {
-		if (typeof segment === "number") return `${formatted}[${segment}]`;
-		return formatted === "" ? String(segment) : `${formatted}.${String(segment)}`;
-	}, "");
-}
 //#endregion
 //#region src/mcp/schema.ts
 const MCP_CAPABILITY_LEVELS = ["default", "optional"];
@@ -382,6 +391,49 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			contextCost: "high",
 			command: "codebase-memory-mcp"
 		})
+	},
+	{
+		name: "github",
+		load: () => ({
+			name: "github",
+			description: "Read repositories, issues, pull requests and workflow runs on GitHub.",
+			transport: "http",
+			contextCost: "high",
+			url: "https://api.githubcopilot.com/mcp/"
+		})
+	},
+	{
+		name: "sentry",
+		load: () => ({
+			name: "sentry",
+			description: "Inspect production issues, events and stack traces recorded by Sentry.",
+			transport: "http",
+			contextCost: "medium",
+			url: "https://mcp.sentry.dev/mcp"
+		})
+	},
+	{
+		name: "chrome-devtools",
+		load: () => ({
+			name: "chrome-devtools",
+			description: "Record performance traces and inspect pages through Chrome DevTools.",
+			transport: "stdio",
+			contextCost: "high",
+			command: "npx",
+			args: ["-y", "chrome-devtools-mcp@latest"]
+		})
+	},
+	{
+		name: "supabase",
+		load: () => ({
+			name: "supabase",
+			description: "Inspect and query Supabase project schemas, tables and logs.",
+			transport: "stdio",
+			contextCost: "high",
+			command: "npx",
+			args: ["-y", "@supabase/mcp-server-supabase@latest"],
+			env: { SUPABASE_ACCESS_TOKEN: { fromEnv: "SUPABASE_ACCESS_TOKEN" } }
+		})
 	}
 ]);
 const builtInMcpServerNames = builtInMcpServerRegistry.names;
@@ -504,6 +556,133 @@ const builtInPacks = [
 			"subagent-driven-development",
 			"requesting-code-review"
 		]
+	},
+	{
+		name: "testing",
+		category: "engineering",
+		description: "Test design, isolation and stability at every level of the pyramid.",
+		skills: [
+			"test-strategy",
+			"test-doubles",
+			"e2e-testing",
+			"flaky-tests"
+		],
+		mcpServers: [{
+			name: "playwright",
+			activation: "optional"
+		}]
+	},
+	{
+		name: "security",
+		category: "engineering",
+		description: "Application security fundamentals for untrusted input, secrets and access.",
+		skills: [
+			"secure-coding",
+			"secrets-handling",
+			"dependency-security",
+			"auth-patterns"
+		]
+	},
+	{
+		name: "performance",
+		category: "engineering",
+		description: "Measure before optimizing, across application, browser and database.",
+		skills: [
+			"performance-profiling",
+			"web-vitals",
+			"query-performance"
+		],
+		mcpServers: [{
+			name: "chrome-devtools",
+			activation: "optional"
+		}]
+	},
+	{
+		name: "accessibility",
+		category: "engineering",
+		description: "Accessible markup, ARIA and keyboard interaction for web interfaces.",
+		skills: [
+			"semantic-html",
+			"aria-patterns",
+			"keyboard-navigation"
+		],
+		mcpServers: [{
+			name: "chrome-devtools",
+			activation: "optional"
+		}]
+	},
+	{
+		name: "refactoring",
+		category: "engineering",
+		description: "Change structure safely, including in legacy code with weak tests.",
+		skills: [
+			"refactoring-safely",
+			"legacy-code",
+			"dependency-hygiene"
+		]
+	},
+	{
+		name: "documentation",
+		category: "engineering",
+		description: "Documentation, interface reference and decision records that stay useful.",
+		skills: [
+			"technical-writing",
+			"api-documentation",
+			"decision-records"
+		]
+	},
+	{
+		name: "observability",
+		category: "engineering",
+		description: "Logging, metrics, tracing and incident response for running systems.",
+		skills: [
+			"structured-logging",
+			"metrics-and-tracing",
+			"incident-response"
+		],
+		mcpServers: [{
+			name: "sentry",
+			activation: "optional"
+		}]
+	},
+	{
+		name: "data",
+		category: "engineering",
+		description: "Schema design, migrations and transactional correctness.",
+		skills: [
+			"data-modeling",
+			"schema-migrations",
+			"transactions-and-consistency"
+		],
+		mcpServers: [{
+			name: "supabase",
+			activation: "optional"
+		}]
+	},
+	{
+		name: "git",
+		category: "workflow",
+		description: "Commit, branch and pull-request practice for reviewable history.",
+		skills: [
+			"commit-hygiene",
+			"branching-strategy",
+			"pull-requests"
+		],
+		mcpServers: [{
+			name: "github",
+			activation: "optional"
+		}]
+	},
+	{
+		name: "devops",
+		category: "workflow",
+		description: "Continuous integration, containers, deployment safety and infrastructure.",
+		skills: [
+			"ci-pipelines",
+			"containerization",
+			"deployment-safety",
+			"infrastructure-as-code"
+		]
 	}
 ];
 /** The registry used by default when no explicit registry is supplied. */
@@ -779,7 +958,40 @@ const builtInSkillNames = [
 	"context-efficient-development",
 	"concise-output",
 	"targeted-exploration",
-	"focused-verification"
+	"focused-verification",
+	"test-strategy",
+	"test-doubles",
+	"e2e-testing",
+	"flaky-tests",
+	"secure-coding",
+	"secrets-handling",
+	"dependency-security",
+	"auth-patterns",
+	"performance-profiling",
+	"web-vitals",
+	"query-performance",
+	"semantic-html",
+	"aria-patterns",
+	"keyboard-navigation",
+	"refactoring-safely",
+	"legacy-code",
+	"dependency-hygiene",
+	"technical-writing",
+	"api-documentation",
+	"decision-records",
+	"structured-logging",
+	"metrics-and-tracing",
+	"incident-response",
+	"data-modeling",
+	"schema-migrations",
+	"transactions-and-consistency",
+	"commit-hygiene",
+	"branching-strategy",
+	"pull-requests",
+	"ci-pipelines",
+	"containerization",
+	"deployment-safety",
+	"infrastructure-as-code"
 ];
 /** The absolute path of a built-in skill's `SKILL.md`. */
 function builtInSkillPath(name) {
@@ -978,6 +1190,182 @@ function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegis
 	};
 }
 //#endregion
+//#region src/manifest/errors.ts
+/** Raised when `.agentyx.lock.json` is not valid JSON. */
+var AgentyxManifestParseError = class extends AgentyxError {
+	filePath;
+	constructor(filePath, reason, options) {
+		super("agentyx_manifest_parse_error", `${filePath} is not valid JSON: ${reason}`, options);
+		this.name = "AgentyxManifestParseError";
+		this.filePath = filePath;
+	}
+};
+/**
+* Raised when the manifest parses as JSON but is not a manifest Agentyx
+* understands.
+*
+* This is never repaired. The manifest is what tells Agentyx which files it is
+* allowed to overwrite and delete, so guessing at a damaged one would be
+* guessing about destructive operations.
+*/
+var AgentyxManifestValidationError = class extends AgentyxError {
+	issues;
+	filePath;
+	constructor(error, filePath) {
+		const issues = toAgentyxIssues(error);
+		const location = filePath === void 0 ? "" : ` in ${filePath}`;
+		const details = issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n");
+		super("agentyx_manifest_invalid", `Invalid Agentyx install manifest${location}:\n${details}\nDelete the file to start from a clean install record.`);
+		this.name = "AgentyxManifestValidationError";
+		this.issues = issues;
+		this.filePath = filePath;
+	}
+};
+//#endregion
+//#region src/manifest/schema.ts
+/**
+* The manifest format version.
+*
+* A manifest written by a newer Agentyx fails validation instead of being
+* reinterpreted, because acting on a half-understood record of managed files is
+* how an installer deletes something it should not.
+*/
+const INSTALL_MANIFEST_VERSION = 1;
+/**
+* A path Agentyx manages, relative to the project root and always written with
+* `/` separators so a manifest reads the same on every platform.
+*/
+const managedPathSchema = z.string().min(1, "Managed paths must be non-empty strings.").refine((value) => !value.startsWith("/"), "Managed paths must be relative to the project root.").refine((value) => !value.includes("\\"), "Managed paths must use `/` separators.").refine((value) => !value.split("/").includes(".."), "Managed paths must not traverse outside the project root.");
+/** A SHA-256 digest of the exact bytes Agentyx last wrote to a managed path. */
+const contentHashSchema = z.string().regex(/^[0-9a-f]{64}$/, "Content hashes must be lowercase hexadecimal SHA-256 digests.");
+const targetsSchema = z.array(z.string().min(1, "Targets must be non-empty strings.")).min(1, "A manifest entry must record at least one target.");
+/** A `SKILL.md` file Agentyx wrote, owned entirely by Agentyx. */
+const skillManifestEntrySchema = z.strictObject({
+	kind: z.literal("skill"),
+	path: managedPathSchema,
+	skill: z.string().min(1, "Skill names must be non-empty strings."),
+	targets: targetsSchema,
+	hash: contentHashSchema
+});
+/**
+* A provider MCP configuration file Agentyx contributed entries to.
+*
+* Unlike a skill file this one is shared with the user, so the entry records
+* the server keys Agentyx added rather than claiming the whole document.
+* `created` says whether the file existed before Agentyx first wrote it, which
+* is the only thing that makes removing the file itself safe.
+*/
+const mcpManifestEntrySchema = z.strictObject({
+	kind: z.literal("mcp"),
+	path: managedPathSchema,
+	servers: z.array(z.string().min(1, "MCP server names must be non-empty strings.")),
+	targets: targetsSchema,
+	hash: contentHashSchema,
+	created: z.boolean()
+});
+const installManifestEntrySchema = z.discriminatedUnion("kind", [skillManifestEntrySchema, mcpManifestEntrySchema]);
+/** The `.agentyx.lock.json` record of everything Agentyx installed into a project. */
+const installManifestSchema = z.strictObject({
+	version: z.literal(1),
+	entries: z.array(installManifestEntrySchema).default([])
+});
+//#endregion
+//#region src/manifest/io.ts
+const AGENTYX_MANIFEST_FILENAME = ".agentyx.lock.json";
+/** The absolute path `.agentyx.lock.json` is read from for a given project. */
+function agentyxManifestPath(projectPath = process.cwd()) {
+	return resolve(projectPath, AGENTYX_MANIFEST_FILENAME);
+}
+/** A manifest that claims nothing — what a project has before its first install. */
+function emptyInstallManifest() {
+	return {
+		version: 1,
+		entries: []
+	};
+}
+/**
+* The SHA-256 digest Agentyx records for managed content.
+*
+* Comparing this digest with the file on disk is what separates "Agentyx wrote
+* this and may replace it" from "someone else owns this file", so it is
+* computed over the exact bytes written, never over a normalised form.
+*/
+function hashContent(content) {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/**
+* Validates an already-parsed manifest document.
+*
+* @throws {AgentyxManifestValidationError} when the document violates the schema.
+*/
+function parseInstallManifest(value, filePath) {
+	const result = installManifestSchema.safeParse(value);
+	if (!result.success) throw new AgentyxManifestValidationError(result.error, filePath);
+	return result.data;
+}
+/**
+* Reads `.agentyx.lock.json` from `projectPath`.
+*
+* A missing manifest is a legitimate state — the project has simply never been
+* installed into — and yields an empty manifest. A manifest that exists but
+* cannot be understood is a hard failure: it governs which files Agentyx may
+* overwrite and delete, and a damaged one is never guessed at.
+*
+* @throws {AgentyxManifestParseError} when the file is not valid JSON.
+* @throws {AgentyxManifestValidationError} when the document violates the schema.
+*/
+async function loadInstallManifest(projectPath = process.cwd()) {
+	const filePath = agentyxManifestPath(projectPath);
+	let contents;
+	try {
+		contents = await readFile(filePath, "utf8");
+	} catch (cause) {
+		if (cause instanceof Error && cause.code === "ENOENT") return emptyInstallManifest();
+		throw cause;
+	}
+	let document;
+	try {
+		document = JSON.parse(contents);
+	} catch (cause) {
+		throw new AgentyxManifestParseError(filePath, cause instanceof Error ? cause.message : String(cause), { cause });
+	}
+	return parseInstallManifest(document, filePath);
+}
+/**
+* Serialises a manifest for writing.
+*
+* Entries and their lists are sorted so that reinstalling an unchanged project
+* produces a byte-identical file and the manifest never shows up as noise in a
+* diff. Writing is deliberately not done here — only the install executor
+* touches the filesystem.
+*/
+function formatInstallManifest(manifest) {
+	const entries = [...manifest.entries].map((entry) => entry.kind === "skill" ? {
+		...entry,
+		targets: sorted(entry.targets)
+	} : {
+		...entry,
+		targets: sorted(entry.targets),
+		servers: sorted(entry.servers)
+	}).sort((left, right) => left.path.localeCompare(right.path));
+	return `${JSON.stringify({
+		version: manifest.version,
+		entries
+	}, null, 2)}\n`;
+}
+/**
+* Indexes manifest entries by managed path.
+*
+* Every ownership question — may this file be overwritten, may it be deleted —
+* is a lookup by path, so callers do not scan the list themselves.
+*/
+function manifestEntriesByPath(manifest) {
+	return new Map(manifest.entries.map((entry) => [entry.path, entry]));
+}
+function sorted(values) {
+	return [...values].sort();
+}
+//#endregion
 //#region src/meta.ts
 const agentyxCoreName = "agentyx-core";
 function getCoreStatus() {
@@ -1139,6 +1527,6 @@ function isNotFound(cause) {
 	return cause instanceof Error && cause.code === "ENOENT";
 }
 //#endregion
-export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, CircularPackDependencyError, DuplicateMcpServerError, DuplicatePackError, DuplicateSkillError, DuplicateToolError, InvalidMcpServerError, InvalidSkillError, InvalidToolError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, PACK_CATEGORIES, TOOL_ACTIVATION_LEVELS, UnknownEnabledCapabilityError, UnknownMcpServerError, UnknownPackError, UnknownSkillError, UnknownToolError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxTargetSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInMcpServerNames, builtInMcpServerRegistry, builtInPackRegistry, builtInPacks, builtInSkillNames, builtInSkillRegistry, builtInToolNames, builtInToolRegistry, collectPackMcpServerReferences, collectPackMcpServers, collectPackToolReferences, createMcpServerRegistry, createPackRegistry, createSkillRegistry, createToolRegistry, detectProject, enabledCapabilityNameSchema, filterEffectiveMcpServers, filterEffectiveTools, formatAgentyxConfig, formatSkillMarkdown, getCoreStatus, loadAgentyxConfig, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, packCategorySchema, packDefinitionSchema, packNameSchema, parseAgentyxConfig, parseSkillMarkdown, resolveAgentyxConfig, resolvePackMcpServerReferences, resolvePackMcpServers, resolvePackSkills, resolvePackToolReferences, resolvePackTools, resolvePacks, skillDefinitionSchema, toolActivationLevelSchema, toolDefinitionSchema, toolNameSchema, toolReferenceSchema };
+export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AGENTYX_MANIFEST_FILENAME, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, AgentyxManifestParseError, AgentyxManifestValidationError, CircularPackDependencyError, DuplicateMcpServerError, DuplicatePackError, DuplicateSkillError, DuplicateToolError, INSTALL_MANIFEST_VERSION, InvalidMcpServerError, InvalidSkillError, InvalidToolError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, PACK_CATEGORIES, TOOL_ACTIVATION_LEVELS, UnknownEnabledCapabilityError, UnknownMcpServerError, UnknownPackError, UnknownSkillError, UnknownToolError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxManifestPath, agentyxTargetSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInMcpServerNames, builtInMcpServerRegistry, builtInPackRegistry, builtInPacks, builtInSkillNames, builtInSkillRegistry, builtInToolNames, builtInToolRegistry, collectPackMcpServerReferences, collectPackMcpServers, collectPackToolReferences, createMcpServerRegistry, createPackRegistry, createSkillRegistry, createToolRegistry, detectProject, emptyInstallManifest, enabledCapabilityNameSchema, filterEffectiveMcpServers, filterEffectiveTools, formatAgentyxConfig, formatInstallManifest, formatSkillMarkdown, getCoreStatus, hashContent, installManifestEntrySchema, installManifestSchema, loadAgentyxConfig, loadInstallManifest, manifestEntriesByPath, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpManifestEntrySchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, packCategorySchema, packDefinitionSchema, packNameSchema, parseAgentyxConfig, parseInstallManifest, parseSkillMarkdown, resolveAgentyxConfig, resolvePackMcpServerReferences, resolvePackMcpServers, resolvePackSkills, resolvePackToolReferences, resolvePackTools, resolvePacks, skillDefinitionSchema, skillManifestEntrySchema, toolActivationLevelSchema, toolDefinitionSchema, toolNameSchema, toolReferenceSchema };
 
 //# sourceMappingURL=index.mjs.map