@agentyx/core 0.5.0 → 0.7.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { access, readFile, readdir, realpath } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { readFileSync } from "node:fs";
+import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { constants, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 //#region src/errors.ts
@@ -97,6 +97,30 @@ var LocalSkillDirectoryError = class extends AgentyxError {
 	}
 };
 //#endregion
+//#region src/hook/schema.ts
+const HOOK_ACTIVATION_LEVELS = ["default", "optional"];
+const hookActivationLevelSchema = z.enum(HOOK_ACTIVATION_LEVELS);
+const HOOK_EVENTS = ["SessionStart"];
+const hookEventSchema = z.enum(HOOK_EVENTS);
+const hookNameSchema = z.string().min(1, "Hook names must be non-empty strings.").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Hook names must be lowercase kebab-case, for example \"session-doctor-bootstrap\".");
+const hookDefinitionSchema = z.strictObject({
+	name: hookNameSchema.describe("Unique hook identifier."),
+	description: z.string().trim().min(1, "Hook descriptions must be non-empty strings."),
+	event: hookEventSchema.describe("The provider lifecycle event this hook runs on."),
+	command: z.string().trim().min(1, "Hook command must be a non-empty string."),
+	args: z.array(z.string()).default([])
+});
+const hookReferenceSchema = z.union([hookNameSchema, z.strictObject({
+	name: hookNameSchema.describe("Hook identifier."),
+	activation: hookActivationLevelSchema.default("default")
+})]).transform((value) => typeof value === "string" ? {
+	name: value,
+	activation: "default"
+} : value).pipe(z.strictObject({
+	name: hookNameSchema.describe("Hook identifier."),
+	activation: hookActivationLevelSchema.describe("Whether this hook is active by default or explicit opt-in.")
+}));
+//#endregion
 //#region src/mcp/schema.ts
 const MCP_CAPABILITY_LEVELS = ["default", "optional"];
 const mcpCapabilityLevelSchema = z.enum(MCP_CAPABILITY_LEVELS);
@@ -106,13 +130,15 @@ const MCP_CONTEXT_COSTS = [
 	"high"
 ];
 const mcpContextCostSchema = z.enum(MCP_CONTEXT_COSTS);
+const mcpRuntimeSchema = z.enum(["local", "may-download"]);
 const mcpServerNameSchema = z.string().min(1, "MCP server names must be non-empty strings.").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "MCP server names must be lowercase kebab-case, for example \"context7\".");
 const mcpEnvReferenceSchema = z.strictObject({ fromEnv: z.string().trim().min(1, "Environment variable references must be non-empty strings.").regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "Environment variable names must be valid shell names.") });
 const commonMcpServerDefinitionSchema = z.strictObject({
 	name: mcpServerNameSchema.describe("Unique MCP server identifier."),
 	description: z.string().trim().min(1, "MCP server descriptions must be non-empty strings."),
 	transport: z.enum(["stdio", "http"]),
-	contextCost: mcpContextCostSchema.describe("Qualitative context/tool-schema overhead classification; not token accounting.").optional()
+	contextCost: mcpContextCostSchema.describe("Qualitative context/tool-schema overhead classification; not token accounting.").optional(),
+	runtime: mcpRuntimeSchema.describe("Whether launching this server can fetch a package on first use; see MCP_RUNTIMES.").optional()
 });
 const explicitMcpServerReferenceSchema = z.strictObject({
 	name: mcpServerNameSchema.describe("MCP server identifier."),
@@ -204,7 +230,8 @@ const packDefinitionSchema = z.strictObject({
 	description: z.string().min(1, "Pack descriptions must be non-empty when provided.").describe("Short human-readable summary of the pack.").optional(),
 	skills: z.array(skillNameSchema).describe("Skills this pack contributes, in declaration order.").default([]),
 	mcpServers: z.array(mcpServerReferenceSchema).describe("MCP servers this pack contributes, in declaration order.").default([]),
-	tools: z.array(toolReferenceSchema).describe("Local tools this pack contributes, in declaration order.").default([])
+	tools: z.array(toolReferenceSchema).describe("Local tools this pack contributes, in declaration order.").default([]),
+	hooks: z.array(hookReferenceSchema).describe("Provider lifecycle hooks this pack contributes, in declaration order.").default([])
 });
 //#endregion
 //#region src/source/schema.ts
@@ -434,6 +461,10 @@ const builtInPacks = [
 		tools: [{
 			name: "rtk",
 			activation: "optional"
+		}],
+		hooks: [{
+			name: "session-doctor-bootstrap",
+			activation: "default"
 		}]
 	},
 	{
@@ -641,14 +672,14 @@ var InvalidSkillError = class extends AgentyxError {
 	origin;
 	reason;
 	constructor(origin, reason, options) {
-		const detail = typeof reason === "string" ? reason : formatIssues$1(reason);
+		const detail = typeof reason === "string" ? reason : formatIssues$2(reason);
 		super("invalid_skill", `Invalid skill in ${origin}: ${detail}`, options);
 		this.name = "InvalidSkillError";
 		this.origin = origin;
 		this.reason = detail;
 	}
 };
-function formatIssues$1(error) {
+function formatIssues$2(error) {
 	return error.issues.map((issue) => {
 		const path = issue.path.map(String).join(".");
 		return path === "" ? issue.message : `${path}: ${issue.message}`;
@@ -969,13 +1000,20 @@ async function loadLocalSkillSources(projectDir, directories) {
 		for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
 			if (!entry.isDirectory()) continue;
 			const filePath = join(rootRealPath, entry.name, "SKILL.md");
-			let markdown;
+			let realFilePath;
 			try {
-				markdown = await readFile(filePath, "utf8");
+				realFilePath = await realpath(filePath);
 			} catch (cause) {
 				if (cause instanceof Error && cause.code === "ENOENT") continue;
 				throw localDirectoryError(directory, `cannot read ${entry.name}/SKILL.md`, cause);
 			}
+			if (!isInside$1(realFilePath, rootRealPath)) throw new LocalSkillDirectoryError(directory, `${entry.name}/SKILL.md resolves outside the skill directory`);
+			let markdown;
+			try {
+				markdown = await readFile(realFilePath, "utf8");
+			} catch (cause) {
+				throw localDirectoryError(directory, `cannot read ${entry.name}/SKILL.md`, cause);
+			}
 			const skill = parseSkillMarkdown(markdown, filePath);
 			if (skill.name !== entry.name) throw new LocalSkillDirectoryError(directory, `${entry.name}/SKILL.md declares the name "${skill.name}"`);
 			sources.push({
@@ -994,6 +1032,149 @@ function localDirectoryError(directory, reason, cause) {
 	return new LocalSkillDirectoryError(directory, reason, cause instanceof Error ? { cause } : void 0);
 }
 //#endregion
+//#region src/hook/errors.ts
+var UnknownHookError = class extends AgentyxError {
+	hookName;
+	requiredBy;
+	knownHooks;
+	constructor(hookName, requiredBy, knownHooks) {
+		const origin = requiredBy === void 0 ? "" : ` (required by "${requiredBy}")`;
+		const known = knownHooks.length > 0 ? [...knownHooks].sort().join(", ") : "none";
+		super("unknown_hook", `Unknown hook "${hookName}"${origin}. Known hooks: ${known}.`);
+		this.name = "UnknownHookError";
+		this.hookName = hookName;
+		this.requiredBy = requiredBy;
+		this.knownHooks = knownHooks;
+	}
+};
+var DuplicateHookError = class extends AgentyxError {
+	hookName;
+	constructor(hookName) {
+		super("duplicate_hook", `Duplicate hook definition: "${hookName}".`);
+		this.name = "DuplicateHookError";
+		this.hookName = hookName;
+	}
+};
+var InvalidHookError = class extends AgentyxError {
+	origin;
+	reason;
+	constructor(origin, reason, options) {
+		const detail = typeof reason === "string" ? reason : formatIssues$1(reason);
+		super("invalid_hook", `Invalid hook in ${origin}: ${detail}`, options);
+		this.name = "InvalidHookError";
+		this.origin = origin;
+		this.reason = detail;
+	}
+};
+function formatIssues$1(error) {
+	return error.issues.map((issue) => {
+		const path = issue.path.map(String).join(".");
+		return path === "" ? issue.message : `${path}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/hook/registry.ts
+function createHookRegistry(sources) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const name = hookNameSchema.safeParse(source.name);
+		if (!name.success) throw new InvalidHookError(`Hook source "${source.name}"`, name.error);
+		if (byName.has(name.data)) throw new DuplicateHookError(name.data);
+		byName.set(name.data, source);
+	}
+	const names = [...byName.keys()];
+	const loaded = /* @__PURE__ */ new Map();
+	const get = (name) => {
+		const cached = loaded.get(name);
+		if (cached !== void 0) return cached;
+		const source = byName.get(name);
+		if (source === void 0) throw new UnknownHookError(name, void 0, names);
+		const origin = `Hook "${name}"`;
+		const hook = hookDefinitionSchema.safeParse(source.load());
+		if (!hook.success) throw new InvalidHookError(origin, hook.error);
+		if (hook.data.name !== name) throw new InvalidHookError(origin, `it declares the name "${hook.data.name}"`);
+		loaded.set(name, hook.data);
+		return hook.data;
+	};
+	return {
+		names,
+		has: (name) => byName.has(name),
+		listMetadata: () => names.map((name) => {
+			const hook = get(name);
+			return {
+				name: hook.name,
+				description: hook.description,
+				event: hook.event
+			};
+		}),
+		get
+	};
+}
+const builtInHookRegistry = createHookRegistry([{
+	name: "session-doctor-bootstrap",
+	load: () => ({
+		name: "session-doctor-bootstrap",
+		description: "Reports Agentyx project health at session start; silent when healthy.",
+		event: "SessionStart",
+		command: "npx",
+		args: [
+			"--no-install",
+			"agentyx",
+			"doctor",
+			"--hook"
+		]
+	})
+}]);
+const builtInHookNames = builtInHookRegistry.names;
+//#endregion
+//#region src/pack/resolver.ts
+/**
+* Resolves selected packs without hidden inheritance.
+*
+* The result preserves configured order, removes duplicates by first
+* occurrence, and validates every requested pack.
+*
+* @throws {UnknownPackError} when a requested pack is missing.
+*/
+function resolvePacks(requestedPacks, registry = builtInPackRegistry) {
+	const resolved = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of requestedPacks) {
+		if (seen.has(name)) continue;
+		if (!registry.has(name)) throw new UnknownPackError(name, void 0, [...registry.keys()]);
+		seen.add(name);
+		resolved.push(name);
+	}
+	return resolved;
+}
+//#endregion
+//#region src/hook/resolver.ts
+function collectPackHookReferences(resolvedPacks, packRegistry, hookRegistry) {
+	const hooks = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const packName of resolvedPacks) for (const hook of packRegistry.get(packName)?.hooks ?? []) {
+		const hookName = hook.name;
+		if (seen.has(hookName)) continue;
+		if (!hookRegistry.has(hookName)) throw new UnknownHookError(hookName, packName, hookRegistry.names);
+		seen.add(hookName);
+		hooks.push(hook);
+	}
+	return hooks;
+}
+function filterEffectiveHooks(hooks, enabledCapabilities) {
+	const enabled = new Set(enabledCapabilities);
+	return hooks.filter((hook) => hook.activation === "default" || enabled.has(hook.name)).map((hook) => hook.name);
+}
+function collectPackHooks(resolvedPacks, packRegistry, hookRegistry, enabledCapabilities = []) {
+	return filterEffectiveHooks(collectPackHookReferences(resolvedPacks, packRegistry, hookRegistry), enabledCapabilities);
+}
+function resolvePackHookReferences(requestedPacks, packRegistry = builtInPackRegistry, hookRegistry = builtInHookRegistry) {
+	return collectPackHookReferences(resolvePacks(requestedPacks, packRegistry), packRegistry, hookRegistry);
+}
+function resolvePackHooks(requestedPacks, packRegistry = builtInPackRegistry, hookRegistry = builtInHookRegistry, enabledCapabilities = []) {
+	return collectPackHooks(resolvePacks(requestedPacks, packRegistry), packRegistry, hookRegistry, enabledCapabilities);
+}
+//#endregion
 //#region src/mcp/errors.ts
 var UnknownMcpServerError = class extends AgentyxError {
 	serverName;
@@ -1067,7 +1248,8 @@ function createMcpServerRegistry(sources) {
 				name: server.name,
 				description: server.description,
 				transport: server.transport,
-				contextCost: server.contextCost
+				contextCost: server.contextCost,
+				runtime: server.runtime
 			};
 		}),
 		get
@@ -1081,6 +1263,7 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Fetch up-to-date library documentation from Context7.",
 			transport: "http",
 			contextCost: "medium",
+			runtime: "local",
 			url: "https://mcp.context7.com/mcp"
 		})
 	},
@@ -1091,8 +1274,9 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Automate and inspect browsers through Playwright MCP.",
 			transport: "stdio",
 			contextCost: "high",
+			runtime: "may-download",
 			command: "npx",
-			args: ["@playwright/mcp@latest"]
+			args: ["@playwright/mcp@0.0.81"]
 		})
 	},
 	{
@@ -1102,6 +1286,7 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Structural code-intelligence MCP backed by a persistent code knowledge graph.",
 			transport: "stdio",
 			contextCost: "high",
+			runtime: "local",
 			command: "codebase-memory-mcp"
 		})
 	},
@@ -1112,6 +1297,7 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Read repositories, issues, pull requests and workflow runs on GitHub.",
 			transport: "http",
 			contextCost: "high",
+			runtime: "local",
 			url: "https://api.githubcopilot.com/mcp/"
 		})
 	},
@@ -1122,6 +1308,7 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Inspect production issues, events and stack traces recorded by Sentry.",
 			transport: "http",
 			contextCost: "medium",
+			runtime: "local",
 			url: "https://mcp.sentry.dev/mcp"
 		})
 	},
@@ -1132,8 +1319,9 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Record performance traces and inspect pages through Chrome DevTools.",
 			transport: "stdio",
 			contextCost: "high",
+			runtime: "may-download",
 			command: "npx",
-			args: ["-y", "chrome-devtools-mcp@latest"]
+			args: ["-y", "chrome-devtools-mcp@1.9.0"]
 		})
 	},
 	{
@@ -1143,35 +1331,15 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 			description: "Inspect and query Supabase project schemas, tables and logs.",
 			transport: "stdio",
 			contextCost: "high",
+			runtime: "may-download",
 			command: "npx",
-			args: ["-y", "@supabase/mcp-server-supabase@latest"],
+			args: ["-y", "@supabase/mcp-server-supabase@0.13.0"],
 			env: { SUPABASE_ACCESS_TOKEN: { fromEnv: "SUPABASE_ACCESS_TOKEN" } }
 		})
 	}
 ]);
 const builtInMcpServerNames = builtInMcpServerRegistry.names;
 //#endregion
-//#region src/pack/resolver.ts
-/**
-* Resolves selected packs without hidden inheritance.
-*
-* The result preserves configured order, removes duplicates by first
-* occurrence, and validates every requested pack.
-*
-* @throws {UnknownPackError} when a requested pack is missing.
-*/
-function resolvePacks(requestedPacks, registry = builtInPackRegistry) {
-	const resolved = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const name of requestedPacks) {
-		if (seen.has(name)) continue;
-		if (!registry.has(name)) throw new UnknownPackError(name, void 0, [...registry.keys()]);
-		seen.add(name);
-		resolved.push(name);
-	}
-	return resolved;
-}
-//#endregion
 //#region src/mcp/resolver.ts
 function collectPackMcpServerReferences(resolvedPacks, packRegistry, mcpRegistry) {
 	const servers = [];
@@ -1347,12 +1515,17 @@ function resolvePackTools(requestedPacks, packRegistry = builtInPackRegistry, to
 * @throws {UnknownPackError} when a configured pack is missing.
 * @throws {UnknownSkillError} when a pack references an unknown skill.
 */
-function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegistry = builtInSkillRegistry, mcpRegistry = builtInMcpServerRegistry, toolRegistry = builtInToolRegistry) {
+function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegistry = builtInSkillRegistry, mcpRegistry = builtInMcpServerRegistry, toolRegistry = builtInToolRegistry, hookRegistry = builtInHookRegistry) {
 	const requestedPacks = [...config.packs];
 	const resolvedPacks = resolvePacks(requestedPacks, registry);
 	const declaredMcpServers = collectPackMcpServerReferences(resolvedPacks, registry, mcpRegistry);
 	const declaredTools = collectPackToolReferences(resolvedPacks, registry, toolRegistry);
-	const knownOptionalCapabilities = [...declaredMcpServers.filter((server) => server.activation === "optional").map((server) => server.name), ...declaredTools.filter((tool) => tool.activation === "optional").map((tool) => tool.name)];
+	const declaredHooks = collectPackHookReferences(resolvedPacks, registry, hookRegistry);
+	const knownOptionalCapabilities = [
+		...declaredMcpServers.filter((server) => server.activation === "optional").map((server) => server.name),
+		...declaredTools.filter((tool) => tool.activation === "optional").map((tool) => tool.name),
+		...declaredHooks.filter((hook) => hook.activation === "optional").map((hook) => hook.name)
+	];
 	for (const capability of config.enable) if (!knownOptionalCapabilities.includes(capability)) throw new UnknownEnabledCapabilityError(capability, knownOptionalCapabilities);
 	return {
 		requestedPacks,
@@ -1362,6 +1535,8 @@ function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegis
 		mcpServers: filterEffectiveMcpServers(declaredMcpServers, config.enable),
 		declaredTools,
 		tools: filterEffectiveTools(declaredTools, config.enable),
+		declaredHooks,
+		hooks: filterEffectiveHooks(declaredHooks, config.enable),
 		enabled: [...config.enable],
 		targets: [...config.targets]
 	};
@@ -1440,7 +1615,26 @@ const mcpManifestEntrySchema = z.strictObject({
 	hash: contentHashSchema,
 	created: z.boolean()
 });
-const installManifestEntrySchema = z.discriminatedUnion("kind", [skillManifestEntrySchema, mcpManifestEntrySchema]);
+/**
+* A provider hook configuration file Agentyx contributed entries to.
+*
+* Shares the `mcp` entry's shape and rationale: the file is shared with the
+* user, so the entry records the hook names Agentyx added rather than
+* claiming the whole document.
+*/
+const hookManifestEntrySchema = z.strictObject({
+	kind: z.literal("hook"),
+	path: managedPathSchema,
+	hooks: z.array(z.string().min(1, "Hook names must be non-empty strings.")),
+	targets: targetsSchema,
+	hash: contentHashSchema,
+	created: z.boolean()
+});
+const installManifestEntrySchema = z.discriminatedUnion("kind", [
+	skillManifestEntrySchema,
+	mcpManifestEntrySchema,
+	hookManifestEntrySchema
+]);
 /** The `.agentyx.lock.json` record of everything Agentyx installed into a project. */
 const installManifestSchema = z.strictObject({
 	version: z.literal(1),
@@ -1517,13 +1711,21 @@ async function loadInstallManifest(projectPath = process.cwd()) {
 * 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)
+	const entries = [...manifest.entries].map((entry) => {
+		if (entry.kind === "skill") return {
+			...entry,
+			targets: sorted(entry.targets)
+		};
+		if (entry.kind === "mcp") return {
+			...entry,
+			targets: sorted(entry.targets),
+			servers: sorted(entry.servers)
+		};
+		return {
+			...entry,
+			targets: sorted(entry.targets),
+			hooks: sorted(entry.hooks)
+		};
 	}).sort((left, right) => left.path.localeCompare(right.path));
 	return `${JSON.stringify({
 		version: manifest.version,
@@ -1549,13 +1751,92 @@ function getCoreStatus() {
 	return "ready";
 }
 //#endregion
-//#region src/project/detector.ts
+//#region src/project/executable.ts
+/** Whether `command` resolves to an executable file, via `PATH` unless it already contains a `/`. */
+async function isExecutableOnPath(command) {
+	if (command.includes("/")) return isFileExecutable(command);
+	for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+		if (directory.length === 0) continue;
+		if (await isFileExecutable(`${directory}/${command}`)) return true;
+	}
+	return false;
+}
+async function isFileExecutable(path) {
+	try {
+		await access(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/project/signals.ts
 const PACKAGE_MANAGERS = [
 	"pnpm",
 	"npm",
 	"yarn",
 	"bun"
 ];
+/** Package name patterns matched exactly, or as a `@scope/*` prefix. */
+const TEST_FRAMEWORK_PATTERNS = [
+	"vitest",
+	"jest",
+	"@jest/*",
+	"@playwright/test",
+	"cypress",
+	"karma"
+];
+const BROWSER_TESTING_PATTERNS = ["@playwright/test", "cypress"];
+const OBSERVABILITY_PATTERNS = ["@sentry/*", "@opentelemetry/*"];
+const DATA_TOOLING_PATTERNS = [
+	"@supabase/*",
+	"drizzle-orm",
+	"prisma",
+	"@prisma/client",
+	"typeorm",
+	"sequelize"
+];
+const ACCESSIBILITY_PATTERNS = [
+	"axe-core",
+	"@axe-core/*",
+	"pa11y"
+];
+const DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+const CONTAINER_IGNORED = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	"coverage"
+]);
+/** Extensions counted as source files by the bounded repository-size scan. */
+const SOURCE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".vue",
+	".svelte",
+	".py",
+	".go",
+	".rs",
+	".java",
+	".kt",
+	".rb",
+	".php",
+	".css",
+	".scss",
+	".html"
+]);
+/** Maximum directory entries visited by `scanRepositorySize`, regardless of match. */
+const REPOSITORY_SCAN_ENTRY_LIMIT = 5e3;
 const lockfileManagers = /* @__PURE__ */ new Map([
 	["pnpm-lock.yaml", "pnpm"],
 	["package-lock.json", "npm"],
@@ -1563,52 +1844,141 @@ const lockfileManagers = /* @__PURE__ */ new Map([
 	["bun.lock", "bun"],
 	["bun.lockb", "bun"]
 ]);
-async function detectProject(projectDir) {
+/** Gathers every project signal with a bounded, cheap set of reads. */
+async function collectProjectSignals(projectDir) {
 	const packageJsonPath = join(projectDir, "package.json");
-	const packageJson = await readPackageJson(packageJsonPath);
-	const packageManager = await detectPackageManager(projectDir, packageJson.data);
-	const detectedPacks = await detectPacks(projectDir, packageJson.data);
+	const packageJsonResult = await readPackageJson(packageJsonPath);
+	const packageJson = packageJsonResult.data;
+	const [packageManager, containers, ci, monorepo, repositorySize, tsconfig, rtkAvailable] = await Promise.all([
+		detectPackageManager(projectDir, packageJson),
+		detectContainerFiles(projectDir),
+		detectCiFiles(projectDir),
+		detectMonorepo(projectDir, packageJson),
+		scanRepositorySize(projectDir),
+		exists(join(projectDir, "tsconfig.json")),
+		isExecutableOnPath(builtInToolRegistry.get("rtk").command)
+	]);
 	return {
 		projectDir,
 		packageJson: {
-			present: packageJson.present,
-			valid: packageJson.valid,
+			present: packageJsonResult.present,
+			valid: packageJsonResult.valid,
 			path: packageJsonPath,
-			name: getString(packageJson.data?.name),
-			packageManager: getString(packageJson.data?.packageManager),
-			error: packageJson.error
+			name: getString(packageJson?.name),
+			packageManager: getString(packageJson?.packageManager),
+			error: packageJsonResult.error
 		},
 		packageManager,
-		detectedPacks,
-		recommendedPacks: recommendPacks(detectedPacks)
+		typescript: {
+			dependency: findDependency(packageJson, "typescript"),
+			tsconfig
+		},
+		angular: findDependency(packageJson, "@angular/core"),
+		testFrameworks: findAnyDependency(packageJson, TEST_FRAMEWORK_PATTERNS),
+		browserTesting: findAnyDependency(packageJson, BROWSER_TESTING_PATTERNS),
+		observability: findAnyDependency(packageJson, OBSERVABILITY_PATTERNS),
+		dataTooling: findAnyDependency(packageJson, DATA_TOOLING_PATTERNS),
+		accessibilityTooling: findAnyDependency(packageJson, ACCESSIBILITY_PATTERNS),
+		containers,
+		ci,
+		monorepo,
+		repositorySize,
+		localTools: { rtkAvailable }
 	};
 }
-function buildAgentyxConfig(input) {
+/**
+* Counts source-like files under a bounded traversal, ignoring dependency, VCS and build output
+* directories. Stops after visiting `entryLimit` directory entries — cheap even on a monorepo — and
+* reports `capped` so callers never mistake a partial scan for a complete one.
+*/
+async function scanRepositorySize(projectDir, options = {}) {
+	const entryLimit = options.entryLimit ?? 5e3;
+	const directories = [projectDir];
+	let filesScanned = 0;
+	let entriesVisited = 0;
+	let capped = false;
+	while (directories.length > 0 && !capped) {
+		const directory = directories.shift();
+		if (directory === void 0) break;
+		let entries;
+		try {
+			entries = await readdir(directory, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entriesVisited >= entryLimit) {
+				capped = true;
+				break;
+			}
+			entriesVisited += 1;
+			if (entry.isDirectory()) {
+				if (entry.name.startsWith(".") || CONTAINER_IGNORED.has(entry.name)) continue;
+				directories.push(join(directory, entry.name));
+			} else if (entry.isFile() && SOURCE_FILE_EXTENSIONS.has(extname(entry.name))) filesScanned += 1;
+		}
+	}
 	return {
-		packs: [...input.packs],
-		enable: [...input.enable ?? []],
-		targets: [...input.targets]
+		filesScanned,
+		capped
 	};
 }
-function formatAgentyxConfig(config) {
-	return `${JSON.stringify(config, null, 2)}\n`;
+function findDependency(packageJson, pattern) {
+	for (const field of DEPENDENCY_FIELDS) {
+		const value = packageJson?.[field];
+		if (!isRecord(value)) continue;
+		if (pattern.endsWith("/*")) {
+			const prefix = pattern.slice(0, -1);
+			const name = Object.keys(value).find((key) => key.startsWith(prefix));
+			if (name !== void 0) return {
+				dependency: name,
+				field
+			};
+			continue;
+		}
+		if (pattern in value) return {
+			dependency: pattern,
+			field
+		};
+	}
 }
-function recommendPacks(detectedPacks) {
-	if (detectedPacks.includes("angular")) return [
-		"technical",
-		"typescript",
-		"angular"
-	];
-	if (detectedPacks.includes("typescript")) return ["technical", "typescript"];
-	return ["technical"];
+function findAnyDependency(packageJson, patterns) {
+	const matches = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) {
+		const match = findDependency(packageJson, pattern);
+		if (match !== void 0 && !seen.has(match.dependency)) {
+			seen.add(match.dependency);
+			matches.push(match);
+		}
+	}
+	return matches;
+}
+async function detectContainerFiles(projectDir) {
+	const [dockerfile, dockerCompose, compose] = await Promise.all([
+		exists(join(projectDir, "Dockerfile")),
+		exists(join(projectDir, "docker-compose.yml")),
+		exists(join(projectDir, "compose.yml"))
+	]);
+	return {
+		dockerfile,
+		compose: dockerCompose || compose
+	};
 }
-async function detectPacks(projectDir, packageJson) {
-	const packs = [];
-	const dependencies = collectDependencies(packageJson);
-	const hasAngular = dependencies.has("@angular/core");
-	if (dependencies.has("typescript") || await exists(join(projectDir, "tsconfig.json")) || hasAngular) packs.push("typescript");
-	if (hasAngular) packs.push("angular");
-	return packs;
+async function detectCiFiles(projectDir) {
+	return { githubActions: await exists(join(projectDir, ".github", "workflows")) };
+}
+async function detectMonorepo(projectDir, packageJson) {
+	const markers = [];
+	if (await exists(join(projectDir, "pnpm-workspace.yaml"))) markers.push("pnpm-workspace.yaml");
+	if (await exists(join(projectDir, "turbo.json"))) markers.push("turbo.json");
+	if (await exists(join(projectDir, "nx.json"))) markers.push("nx.json");
+	const workspaces = packageJson?.workspaces;
+	if (Array.isArray(workspaces) || isRecord(workspaces)) markers.push("package.json workspaces");
+	return {
+		detected: markers.length > 0,
+		markers
+	};
 }
 async function detectPackageManager(projectDir, packageJson) {
 	const lockfiles = [];
@@ -1671,16 +2041,6 @@ async function readPackageJson(path) {
 		};
 	}
 }
-function collectDependencies(packageJson) {
-	const dependencies = /* @__PURE__ */ new Set();
-	for (const field of [
-		packageJson?.dependencies,
-		packageJson?.devDependencies,
-		packageJson?.peerDependencies,
-		packageJson?.optionalDependencies
-	]) if (isRecord(field)) for (const name of Object.keys(field)) dependencies.add(name);
-	return dependencies;
-}
 function parsePackageManagerName(value) {
 	const name = value?.split("@")[0];
 	return PACKAGE_MANAGERS.includes(name) ? name : void 0;
@@ -1704,6 +2064,128 @@ function isNotFound(cause) {
 	return cause instanceof Error && cause.code === "ENOENT";
 }
 //#endregion
+//#region src/project/detector.ts
+/**
+* Factual project detection only. It gathers `ProjectSignals` and never decides which packs or
+* capabilities fit — that policy lives in `recommendCapabilities`, kept separate so each half stays
+* independently testable.
+*/
+async function detectProject(projectDir) {
+	const signals = await collectProjectSignals(projectDir);
+	return {
+		projectDir,
+		packageJson: signals.packageJson,
+		packageManager: signals.packageManager,
+		signals
+	};
+}
+function buildAgentyxConfig(input) {
+	return {
+		packs: [...input.packs],
+		enable: [...input.enable ?? []],
+		targets: [...input.targets]
+	};
+}
+function formatAgentyxConfig(config) {
+	return `${JSON.stringify(config, null, 2)}\n`;
+}
+//#endregion
+//#region src/project/recommend.ts
+const RECOMMENDATION_CONFIDENCES = ["high", "medium"];
+/**
+* Heuristic thresholds for the `codebase-memory` capability suggestion, in scanned source files.
+* These are approximate signals, not exact token accounting, and a monorepo is treated as already
+* complex enough to lower the bar.
+*/
+const CODEBASE_MEMORY_FILE_THRESHOLD = 2e3;
+const CODEBASE_MEMORY_MONOREPO_FILE_THRESHOLD = 800;
+/**
+* Applies conservative, deterministic policy on top of `ProjectSignals`. This is the only place
+* that turns an observed fact into a product suggestion — `ProjectSignals` stays fact-only so it
+* can be tested independently of pack names or capability policy.
+*
+* Never enables anything and never touches the filesystem: the caller decides what, if anything,
+* to do with the result.
+*/
+function recommendCapabilities(signals, options = {}) {
+	const packs = recommendPacks(signals);
+	const configuredPacks = options.configuredPacks ?? [];
+	return {
+		packs,
+		capabilities: recommendOptionalCapabilities(signals, /* @__PURE__ */ new Set([...packs.map((pack) => pack.name), ...configuredPacks]), configuredPacks)
+	};
+}
+function recommendPacks(signals) {
+	const packs = [];
+	if (signals.packageJson.present) packs.push(packRecommendation("technical", "high", ["package.json detected — baseline engineering practices apply to any software project."]));
+	const typescriptReasons = [...signals.typescript.dependency !== void 0 ? [dependencyReason("TypeScript", signals.typescript.dependency)] : [], ...signals.typescript.tsconfig ? ["tsconfig.json detected."] : []];
+	if (typescriptReasons.length > 0) packs.push(packRecommendation("typescript", "high", typescriptReasons));
+	if (signals.angular !== void 0) packs.push(packRecommendation("angular", "high", [dependencyReason("@angular/core", signals.angular)]));
+	const testingMatches = dedupeMatches([...signals.testFrameworks, ...signals.browserTesting]);
+	if (testingMatches.length > 0) packs.push(packRecommendation("testing", "high", testingMatches.map((match) => dependencyReason(match.dependency, match))));
+	const devopsReasons = [
+		...signals.containers.dockerfile ? ["Dockerfile detected."] : [],
+		...signals.containers.compose ? ["Container compose file detected."] : [],
+		...signals.ci.githubActions ? ["GitHub Actions workflow detected (.github/workflows)."] : []
+	];
+	if (devopsReasons.length > 0) packs.push(packRecommendation("devops", "high", devopsReasons));
+	if (signals.observability.length > 0) packs.push(packRecommendation("observability", "high", signals.observability.map((match) => dependencyReason(match.dependency, match))));
+	if (signals.dataTooling.length > 0) packs.push(packRecommendation("data", "high", signals.dataTooling.map((match) => dependencyReason(match.dependency, match))));
+	if (signals.accessibilityTooling.length > 0) packs.push(packRecommendation("accessibility", "high", signals.accessibilityTooling.map((match) => dependencyReason(match.dependency, match))));
+	return packs;
+}
+function recommendOptionalCapabilities(signals, activePacks, configuredPacks) {
+	const capabilities = [];
+	const playwrightMatch = signals.browserTesting.find((match) => match.dependency === "@playwright/test");
+	if (activePacks.has("testing") && playwrightMatch !== void 0) capabilities.push(capabilityRecommendation("playwright", "high", ["Playwright is already part of this project; browser MCP may be useful for interactive browser work."]));
+	if (signals.observability.find((match) => match.dependency.startsWith("@sentry/")) !== void 0) capabilities.push(capabilityRecommendation("sentry", "high", ["Sentry is already configured as a dependency."]));
+	if (signals.dataTooling.find((match) => match.dependency.startsWith("@supabase/")) !== void 0) capabilities.push(capabilityRecommendation("supabase", "high", ["Supabase is already configured as a dependency."]));
+	if (configuredPacks.includes("efficiency") && signals.localTools.rtkAvailable) capabilities.push(capabilityRecommendation("rtk", "high", ["RTK is already installed locally."]));
+	const sizeThreshold = signals.monorepo.detected ? 800 : CODEBASE_MEMORY_FILE_THRESHOLD;
+	if (signals.repositorySize.filesScanned >= sizeThreshold || signals.repositorySize.capped) capabilities.push(capabilityRecommendation("codebase-memory", "medium", [repositorySizeReason(signals)]));
+	return capabilities;
+}
+function repositorySizeReason(signals) {
+	const { filesScanned, capped } = signals.repositorySize;
+	const scope = signals.monorepo.detected ? " across this monorepo" : "";
+	return `Heuristic: found ${capped ? `at least ${filesScanned} source files (the scan was capped before finishing)` : `${filesScanned} source files`}${scope}. A persistent codebase-memory MCP may reduce repeated full-tree reads on a repository this size — this is an approximate signal, not an exact token measurement.`;
+}
+function packRecommendation(name, confidence, reasons) {
+	return {
+		kind: "pack",
+		name,
+		confidence,
+		reasons
+	};
+}
+/** Provenance comes from the pack registry itself — never a second, hand-maintained capability map. */
+function capabilityRecommendation(name, confidence, reasons) {
+	return {
+		kind: "capability",
+		name,
+		confidence,
+		reasons,
+		contributedBy: packsDeclaringOptionalCapability(name)
+	};
+}
+function packsDeclaringOptionalCapability(name) {
+	const packs = [];
+	for (const pack of builtInPackRegistry.values()) if (pack.mcpServers.some((server) => server.name === name && server.activation === "optional") || pack.tools.some((tool) => tool.name === name && tool.activation === "optional") || pack.hooks.some((hook) => hook.name === name && hook.activation === "optional")) packs.push(pack.name);
+	return packs;
+}
+function dependencyReason(label, match) {
+	return label === match.dependency ? `Detected ${match.dependency} in ${match.field}.` : `Detected ${label} (${match.dependency}) in ${match.field}.`;
+}
+function dedupeMatches(matches) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const match of matches) if (!seen.has(match.dependency)) {
+		seen.add(match.dependency);
+		result.push(match);
+	}
+	return result;
+}
+//#endregion
 //#region src/source/inspection.ts
 async function inspectTrustedSource(projectPath, reference) {
 	const definition = getTrustedSourceDefinition(reference);
@@ -1792,6 +2274,6 @@ function trustedSourceLoadError(sourceName, reason, cause) {
 	return new TrustedSourceLoadError(sourceName, reason, cause instanceof Error ? { cause } : void 0);
 }
 //#endregion
-export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AGENTYX_MANIFEST_FILENAME, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, AgentyxManifestParseError, AgentyxManifestValidationError, CircularPackDependencyError, DuplicateMcpServerError, DuplicatePackError, DuplicateSkillError, DuplicateToolError, DuplicateTrustedSourceError, INSTALL_MANIFEST_VERSION, InvalidMcpServerError, InvalidSkillError, InvalidToolError, LocalSkillDirectoryError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, PACK_CATEGORIES, TOOL_ACTIVATION_LEVELS, TrustedSourceLoadError, UnknownEnabledCapabilityError, UnknownMcpServerError, UnknownPackError, UnknownSkillError, UnknownToolError, UnknownTrustedSourceError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxManifestPath, agentyxTargetSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInMcpServerNames, builtInMcpServerRegistry, builtInPackRegistry, builtInPacks, builtInSkillNames, builtInSkillRegistry, builtInToolNames, builtInToolRegistry, codexPluginManifestSchema, collectPackMcpServerReferences, collectPackMcpServers, collectPackToolReferences, createMcpServerRegistry, createPackRegistry, createSkillRegistry, createToolRegistry, createTrustedSourceRegistry, detectProject, emptyInstallManifest, enabledCapabilityNameSchema, filterEffectiveMcpServers, filterEffectiveTools, formatAgentyxConfig, formatInstallManifest, formatSkillMarkdown, getCoreStatus, getTrustedSourceDefinition, hashContent, inspectTrustedSource, installManifestEntrySchema, installManifestSchema, knownTrustedSourceRegistry, knownTrustedSources, loadAgentyxConfig, loadAgentyxProject, loadInstallManifest, manifestEntriesByPath, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpManifestEntrySchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, packCategorySchema, packDefinitionSchema, packNameSchema, parseAgentyxConfig, parseInstallManifest, parseSkillMarkdown, resolveAgentyxConfig, resolvePackMcpServerReferences, resolvePackMcpServers, resolvePackSkills, resolvePackToolReferences, resolvePackTools, resolvePacks, skillDefinitionSchema, skillDirectorySchema, skillManifestEntrySchema, toolActivationLevelSchema, toolDefinitionSchema, toolNameSchema, toolReferenceSchema, trustedSourceDefinitionSchema, trustedSourceNameSchema, trustedSourcePathSchema, trustedSourceReferenceSchema, trustedSourceSkillSummarySchema };
+export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AGENTYX_MANIFEST_FILENAME, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, AgentyxManifestParseError, AgentyxManifestValidationError, CODEBASE_MEMORY_FILE_THRESHOLD, CODEBASE_MEMORY_MONOREPO_FILE_THRESHOLD, CircularPackDependencyError, DuplicateHookError, DuplicateMcpServerError, DuplicatePackError, DuplicateSkillError, DuplicateToolError, DuplicateTrustedSourceError, HOOK_ACTIVATION_LEVELS, HOOK_EVENTS, INSTALL_MANIFEST_VERSION, InvalidHookError, InvalidMcpServerError, InvalidSkillError, InvalidToolError, LocalSkillDirectoryError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, PACK_CATEGORIES, RECOMMENDATION_CONFIDENCES, REPOSITORY_SCAN_ENTRY_LIMIT, TOOL_ACTIVATION_LEVELS, TrustedSourceLoadError, UnknownEnabledCapabilityError, UnknownHookError, UnknownMcpServerError, UnknownPackError, UnknownSkillError, UnknownToolError, UnknownTrustedSourceError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxManifestPath, agentyxTargetSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInHookNames, builtInHookRegistry, builtInMcpServerNames, builtInMcpServerRegistry, builtInPackRegistry, builtInPacks, builtInSkillNames, builtInSkillRegistry, builtInToolNames, builtInToolRegistry, codexPluginManifestSchema, collectPackHookReferences, collectPackHooks, collectPackMcpServerReferences, collectPackMcpServers, collectPackToolReferences, collectProjectSignals, createHookRegistry, createMcpServerRegistry, createPackRegistry, createSkillRegistry, createToolRegistry, createTrustedSourceRegistry, detectProject, emptyInstallManifest, enabledCapabilityNameSchema, filterEffectiveHooks, filterEffectiveMcpServers, filterEffectiveTools, formatAgentyxConfig, formatInstallManifest, formatSkillMarkdown, getCoreStatus, getTrustedSourceDefinition, hashContent, hookActivationLevelSchema, hookDefinitionSchema, hookEventSchema, hookManifestEntrySchema, hookNameSchema, hookReferenceSchema, inspectTrustedSource, installManifestEntrySchema, installManifestSchema, isExecutableOnPath, knownTrustedSourceRegistry, knownTrustedSources, loadAgentyxConfig, loadAgentyxProject, loadInstallManifest, manifestEntriesByPath, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpManifestEntrySchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, packCategorySchema, packDefinitionSchema, packNameSchema, parseAgentyxConfig, parseInstallManifest, parseSkillMarkdown, recommendCapabilities, resolveAgentyxConfig, resolvePackHookReferences, resolvePackHooks, resolvePackMcpServerReferences, resolvePackMcpServers, resolvePackSkills, resolvePackToolReferences, resolvePackTools, resolvePacks, scanRepositorySize, skillDefinitionSchema, skillDirectorySchema, skillManifestEntrySchema, toolActivationLevelSchema, toolDefinitionSchema, toolNameSchema, toolReferenceSchema, trustedSourceDefinitionSchema, trustedSourceNameSchema, trustedSourcePathSchema, trustedSourceReferenceSchema, trustedSourceSkillSummarySchema };
 
 //# sourceMappingURL=index.mjs.map