@happyvertical/smrt-dev-mcp 0.40.63 → 0.40.65

package/dist/{knowledge-CCX7oQzQ.js → knowledge-A7-gIjW4.js}

@@ -4,6 +4,680 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { MODULE_DOC_HASH_PREFIX, readAgentModuleDocs } from "@happyvertical/smrt-core/knowledge";
 import { ManifestAdapter, OxcScanner } from "@happyvertical/smrt-scanner";
+//#region src/tool-catalog.ts
+var REVIEW_SKILL_NAME = "smrt-code-review";
+var JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+function compareToolNames(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+* Stable success/error envelope for development tools. `data` preserves each
+* tool's existing payload exactly; coverage/diagnostics are promoted only when
+* the underlying result actually reports them.
+*/
+var DEV_MCP_OUTPUT_SCHEMA = {
+	$schema: JSON_SCHEMA_2020_12,
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"ok",
+		"coverage",
+		"diagnostics",
+		"data"
+	],
+	properties: {
+		ok: { type: "boolean" },
+		coverage: {
+			type: ["object", "null"],
+			additionalProperties: true
+		},
+		diagnostics: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: true
+			}
+		},
+		data: {}
+	}
+};
+var TOOLS = [
+	{
+		name: "generate-smrt-class",
+		description: "Generate a complete SMRT class with @smrt() decorator",
+		inputSchema: {
+			type: "object",
+			properties: {
+				className: {
+					type: "string",
+					description: "Name of the class (PascalCase)"
+				},
+				properties: {
+					type: "array",
+					description: "Array of property definitions",
+					items: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							type: {
+								type: "string",
+								enum: [
+									"text",
+									"integer",
+									"decimal",
+									"boolean",
+									"datetime",
+									"json"
+								]
+							},
+							required: { type: "boolean" },
+							nullable: { type: "boolean" },
+							description: { type: "string" },
+							defaultValue: { oneOf: [
+								{ type: "string" },
+								{ type: "number" },
+								{ type: "boolean" },
+								{ type: "object" },
+								{ type: "null" }
+							] }
+						},
+						required: ["name", "type"]
+					}
+				},
+				baseClass: {
+					type: "string",
+					enum: ["SmrtObject", "SmrtCollection"],
+					default: "SmrtObject"
+				},
+				template: {
+					type: "string",
+					enum: [
+						"basic",
+						"global-catalog",
+						"optional-catalog",
+						"tenant-project-object",
+						"tenant-event-log-object",
+						"cross-package-reference"
+					],
+					default: "basic"
+				},
+				tableName: { type: "string" },
+				conflictColumns: {
+					type: "array",
+					items: { type: "string" }
+				},
+				tenantScoped: { oneOf: [{ type: "boolean" }, {
+					type: "object",
+					properties: {
+						mode: {
+							type: "string",
+							enum: ["required", "optional"]
+						},
+						field: { type: "string" },
+						autoFilter: { type: "boolean" },
+						autoPopulate: { type: "boolean" },
+						allowSuperAdminBypass: { type: "boolean" }
+					}
+				}] },
+				includeTenantIdField: { type: "boolean" },
+				relationships: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							type: {
+								type: "string",
+								enum: [
+									"foreignKey",
+									"crossPackageRef",
+									"oneToMany",
+									"manyToMany"
+								]
+							},
+							related: { type: "string" },
+							required: { type: "boolean" },
+							nullable: { type: "boolean" },
+							description: { type: "string" },
+							validate: { type: "boolean" },
+							foreignKey: { type: "string" },
+							through: { type: "string" },
+							sourceKey: { type: "string" },
+							targetKey: { type: "string" }
+						},
+						required: [
+							"name",
+							"type",
+							"related"
+						]
+					}
+				},
+				includeCompanionSnippets: {
+					type: "boolean",
+					default: false
+				},
+				includeApiConfig: {
+					type: "boolean",
+					default: true
+				},
+				includeMcpConfig: {
+					type: "boolean",
+					default: true
+				},
+				includeCliConfig: {
+					type: "boolean",
+					default: true
+				}
+			},
+			required: ["className", "properties"]
+		}
+	},
+	{
+		name: "introspect-project",
+		description: "Scan a directory for SMRT objects. Returns a compact summary by default; pass detail: \"full\" for field, schema, and method details.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				directory: {
+					type: "string",
+					description: "Project directory (default: cwd)"
+				},
+				manifestPath: {
+					type: "string",
+					description: "Optional manifest path. Defaults to .smrt/manifest.json, dist/manifest.json, then source scanning."
+				},
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: one compact record per object. full: complete field/schema/method detail (large)."
+				},
+				maxChars: {
+					type: "number",
+					description: "Character budget for the `objects` payload. Objects past the budget are omitted and reported under `truncated`. Project metadata and diagnostics are always returned in full, so the serialized response is somewhat larger than this budget."
+				},
+				includeFields: {
+					type: "boolean",
+					description: "Include field details (detail: \"full\" only)"
+				},
+				includeRelationships: {
+					type: "boolean",
+					description: "Analyze relationships (detail: \"full\" only)"
+				},
+				includeMethods: {
+					type: "boolean",
+					description: "Include public method details (detail: \"full\" only)"
+				}
+			}
+		}
+	},
+	{
+		name: "review-smrt-project",
+		description: "Advisory ecosystem alignment review for downstream SMRT projects",
+		inputSchema: {
+			type: "object",
+			properties: {
+				directory: {
+					type: "string",
+					description: "Project directory (default: cwd)"
+				},
+				rootDir: {
+					type: "string",
+					description: "Compatibility alias for directory"
+				},
+				includeSourceEvidence: {
+					type: "boolean",
+					description: "Include file and line evidence in findings",
+					default: true
+				},
+				maxFindings: {
+					type: "number",
+					description: "Optional maximum number of findings to return"
+				}
+			}
+		}
+	},
+	{
+		name: "reflect-knowledge",
+		description: "Report deterministic SMRT + HappyVertical SDK knowledge coverage and freshness",
+		inputSchema: {
+			type: "object",
+			properties: { rootDir: {
+				type: "string",
+				description: "Project root directory (default: cwd)"
+			} }
+		}
+	},
+	{
+		name: "reflect-domain-knowledge",
+		description: "Report domain-scoped SMRT knowledge artifacts, SDK packages, and freshness",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" }
+			}
+		}
+	},
+	{
+		name: "check-knowledge-freshness",
+		description: "Run deterministic freshness checks for SMRT agent knowledge",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changed: {
+					type: "boolean",
+					description: "Limit stale-pattern checks to changed files"
+				},
+				strict: {
+					type: "boolean",
+					description: "Treat stale-pattern findings as errors"
+				}
+			}
+		}
+	},
+	{
+		name: "check-domain-knowledge",
+		description: "Run deterministic freshness checks for domain knowledge artifacts",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changed: { type: "boolean" },
+				strict: { type: "boolean" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" }
+			}
+		}
+	},
+	{
+		name: "build-review-context",
+		description: "Build model-ready SMRT review context from changed files and optional focus text",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changedFiles: {
+					type: "array",
+					items: { type: "string" }
+				},
+				focus: { type: "string" },
+				documentation: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "build-domain-review-context",
+		description: "Build domain-scoped model-ready SMRT review context and prompt bundle",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changedFiles: {
+					type: "array",
+					items: { type: "string" }
+				},
+				focus: { type: "string" },
+				documentation: { type: "string" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "smrt-review",
+		description: "Return deterministic review findings and/or a reusable model prompt bundle. For a formal downstream review, first call get-agent-skill with { \"name\": \"smrt-code-review\" } or load the smrt-code-review MCP prompt/resource.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changedFiles: {
+					type: "array",
+					items: { type: "string" }
+				},
+				focus: { type: "string" },
+				documentation: { type: "string" },
+				mode: {
+					type: "string",
+					enum: [
+						"findings",
+						"prompt-bundle",
+						"both"
+					],
+					default: "both"
+				},
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "build-architecture-context",
+		description: "Build model-ready SMRT architecture context from an idea or documentation",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				idea: { type: "string" },
+				documentation: { type: "string" },
+				focus: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "build-domain-architecture-context",
+		description: "Build domain-scoped model-ready SMRT architecture context and prompt bundle",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				idea: { type: "string" },
+				documentation: { type: "string" },
+				focus: { type: "string" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "smrt-architecture",
+		description: "Suggest SMRT and HappyVertical SDK packages and return an architecture prompt bundle",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				idea: { type: "string" },
+				documentation: { type: "string" },
+				focus: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "list-agent-skills",
+		description: "List bundled harness-agnostic agent skills shipped with smrt-dev-mcp",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	},
+	{
+		name: "get-agent-skill",
+		description: "Return a bundled harness-agnostic agent skill as Markdown plus optional references",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: {
+					type: "string",
+					enum: [REVIEW_SKILL_NAME],
+					description: "Bundled agent skill name"
+				},
+				includeReferences: {
+					type: "boolean",
+					default: true,
+					description: "Include referenced files with the skill bundle"
+				}
+			},
+			required: ["name"]
+		}
+	}
+].map((tool) => ({
+	...tool,
+	inputSchema: {
+		...tool.inputSchema,
+		$schema: JSON_SCHEMA_2020_12
+	},
+	outputSchema: DEV_MCP_OUTPUT_SCHEMA
+})).sort((left, right) => compareToolNames(left.name, right.name));
+//#endregion
+//#region src/knowledge/mcp-docs.ts
+var PACKAGE_NAME = "@happyvertical/smrt-dev-mcp";
+/**
+* Compare the authored development-MCP catalog to the actual exported tools.
+* The parser intentionally checks only stable structural Markdown: tool names
+* plus top-level input-property names, types, enums, and requiredness.
+* Descriptive prose and prose-embedded defaults remain authored.
+*/
+function checkMcpToolDocumentation(rootDir, packageDir, tools) {
+	const readmePath = join(packageDir, "README.md");
+	const agentsPath = join(packageDir, "AGENTS.md");
+	const issues = [];
+	if (!existsSync(readmePath)) {
+		issues.push(issue(rootDir, readmePath, "mcp-readme-missing", "MCP package README.md is missing"));
+		return issues;
+	}
+	const expectedTools = [...tools].sort((left, right) => compareNames(left.name, right.name));
+	const { sections: readmeSections, names: documentedToolNames } = readToolSections(readFileSync(readmePath, "utf8"));
+	const expectedToolNames = expectedTools.map((tool) => tool.name);
+	const readmeCatalogDiff = setDifference(expectedToolNames, documentedToolNames);
+	if (readmeCatalogDiff) issues.push(issue(rootDir, readmePath, "mcp-readme-tool-drift", `README tool catalog differs from exported TOOLS (${readmeCatalogDiff})`));
+	for (const tool of expectedTools) {
+		const section = readmeSections.get(tool.name);
+		if (section === void 0) continue;
+		const { parameters: documentedParameters, names: documentedParameterNames } = readParameterTable(section);
+		const expectedProperties = Object.keys(tool.inputSchema.properties ?? {}).sort(compareNames);
+		const propertyDiff = setDifference(expectedProperties, documentedParameterNames);
+		const required = new Set(tool.inputSchema.required ?? []);
+		const requiredness = expectedProperties.filter((name) => documentedParameters.has(name) && documentedParameters.get(name)?.required !== required.has(name)).map((name) => `${name} expected ${required.has(name) ? "Yes" : "No"} but documented ${documentedParameters.get(name)?.required ? "Yes" : "No"}`);
+		const inputProperties = tool.inputSchema.properties ?? {};
+		const types = expectedProperties.filter((name) => documentedParameters.has(name)).flatMap((name) => {
+			const expected = formatSchemaType(inputProperties[name]);
+			const documented = documentedParameters.get(name)?.type;
+			return documented === expected ? [] : [`${name} expected ${expected} but documented ${documented}`];
+		});
+		const details = [
+			propertyDiff,
+			requiredness.length > 0 ? `requiredness: ${requiredness.join(", ")}` : void 0,
+			types.length > 0 ? `types: ${types.join(", ")}` : void 0
+		].filter((value) => Boolean(value));
+		if (details.length > 0) issues.push(issue(rootDir, readmePath, "mcp-readme-schema-drift", `README parameters for "${tool.name}" differ from its exported input schema (${details.join("; ")})`));
+	}
+	if (!existsSync(agentsPath)) return issues;
+	const agentsCatalogDiff = setDifference(expectedToolNames, readAgentToolNames(readFileSync(agentsPath, "utf8")).sort(compareNames));
+	if (agentsCatalogDiff) issues.push(issue(rootDir, agentsPath, "mcp-agents-tool-drift", `AGENTS.md tool catalog differs from exported TOOLS (${agentsCatalogDiff})`));
+	return issues;
+}
+function issue(rootDir, path, code, message) {
+	return {
+		severity: "error",
+		code,
+		message,
+		file: relative(rootDir, path),
+		packageName: PACKAGE_NAME
+	};
+}
+function readToolSections(markdown) {
+	const availableTools = sectionAfterHeading(markdown, "Available Tools");
+	if (!availableTools) return {
+		sections: /* @__PURE__ */ new Map(),
+		names: []
+	};
+	const headings = [...availableTools.matchAll(/^### `([^`]+)`\s*$/gm)];
+	return {
+		sections: new Map(headings.map((heading, index) => {
+			const start = (heading.index ?? 0) + heading[0].length;
+			const end = headings[index + 1]?.index ?? availableTools.length;
+			return [heading[1], availableTools.slice(start, end)];
+		})),
+		names: headings.map((heading) => heading[1])
+	};
+}
+function readParameterTable(section) {
+	const parameters = /* @__PURE__ */ new Map();
+	const names = [];
+	for (const line of section.split("\n")) {
+		if (!line.trimStart().startsWith("|")) continue;
+		const cells = splitMarkdownRow(line);
+		const name = /^`([^`]+)`$/.exec(cells[0]?.trim() ?? "")?.[1];
+		const required = cells[2]?.trim();
+		if (!name || required !== "Yes" && required !== "No") continue;
+		names.push(name);
+		parameters.set(name, {
+			name,
+			required: required === "Yes",
+			type: normalizeDocumentedType(cells[1] ?? "")
+		});
+	}
+	return {
+		parameters,
+		names
+	};
+}
+function normalizeDocumentedType(value) {
+	const trimmed = value.trim();
+	return (trimmed.startsWith("`") && trimmed.endsWith("`") ? trimmed.slice(1, -1) : trimmed).replaceAll("\\|", "|").replace(/\s*\|\s*/g, " | ").trim();
+}
+function formatSchemaType(value) {
+	if (!isRecord(value)) return "unknown";
+	if (Array.isArray(value.oneOf)) return unique(value.oneOf.map(formatSchemaType)).join(" | ");
+	if (Array.isArray(value.enum) && value.enum.length > 0) return value.enum.map(formatEnumValue).join(" | ");
+	if (value.type === "array") {
+		const itemType = formatSchemaType(value.items);
+		return itemType.includes(" | ") ? `(${itemType})[]` : `${itemType}[]`;
+	}
+	if (Array.isArray(value.type)) return unique(value.type.map(String)).join(" | ");
+	return typeof value.type === "string" ? value.type : "unknown";
+}
+function formatEnumValue(value) {
+	if (typeof value === "string") return `'${value.replaceAll("'", "\\'")}'`;
+	return String(value);
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+function splitMarkdownRow(row) {
+	const content = row.trim().replace(/^\|/, "").replace(/\|$/, "");
+	const cells = [];
+	let cell = "";
+	for (let index = 0; index < content.length; index += 1) {
+		const character = content[index];
+		if (character === "|" && content[index - 1] !== "\\") {
+			cells.push(cell);
+			cell = "";
+		} else cell += character;
+	}
+	cells.push(cell);
+	return cells;
+}
+function readAgentToolNames(markdown) {
+	const toolsSection = sectionAfterHeading(markdown, "Tools");
+	if (!toolsSection) return [];
+	return [...toolsSection.matchAll(/^\|\s*`([^`]+)`\s*\|/gm)].map((match) => match[1]);
+}
+function sectionAfterHeading(markdown, heading) {
+	const marker = new RegExp(`^## ${heading}\\s*$`, "m").exec(markdown);
+	if (!marker) return "";
+	const start = (marker.index ?? 0) + marker[0].length;
+	const remainder = markdown.slice(start);
+	const nextHeading = /^##\s+/m.exec(remainder);
+	return remainder.slice(0, nextHeading?.index ?? remainder.length);
+}
+function setDifference(expected, actual) {
+	const expectedSet = new Set(expected);
+	const actualSet = new Set(actual);
+	const missing = expected.filter((value) => !actualSet.has(value)).sort(compareNames);
+	const extra = unique(actual.filter((value) => !expectedSet.has(value))).sort(compareNames);
+	const expectedDuplicates = duplicateNames(expected);
+	const actualDuplicates = duplicateNames(actual);
+	const parts = [
+		missing.length > 0 ? `missing: ${missing.join(", ")}` : void 0,
+		extra.length > 0 ? `extra: ${extra.join(", ")}` : void 0,
+		expectedDuplicates.length > 0 ? `exported duplicates: ${expectedDuplicates.join(", ")}` : void 0,
+		actualDuplicates.length > 0 ? `duplicates: ${actualDuplicates.join(", ")}` : void 0
+	].filter((value) => Boolean(value));
+	return parts.length > 0 ? parts.join("; ") : void 0;
+}
+function duplicateNames(values) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const value of values) {
+		if (seen.has(value)) duplicates.add(value);
+		seen.add(value);
+	}
+	return [...duplicates].sort(compareNames);
+}
+function compareNames(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+//#endregion
 //#region src/knowledge/index.ts
 var SDK_PACKAGE_NAMES = /* @__PURE__ */ new Set([
 	"@happyvertical/ai",
@@ -332,6 +1006,8 @@ async function checkKnowledgeFreshnessFromIndex(index, options = {}) {
 		});
 	}
 	for (const pkg of authoredPackages) issues.push(...checkDomainKnowledgeArtifact(index.rootDir, pkg));
+	const devMcpPackage = authoredPackages.find((pkg) => pkg.name === "@happyvertical/smrt-dev-mcp");
+	if (devMcpPackage) issues.push(...checkMcpToolDocumentation(index.rootDir, devMcpPackage.directory, TOOLS));
 	issues.push(...findStalePatternIssues(index.rootDir, changedFiles));
 	const effectiveIssues = issues.map((issue) => issue.code.startsWith("stale-") ? {
 		...issue,
@@ -1926,6 +2602,6 @@ function sortJson(value) {
 	return value;
 }
 //#endregion
-export { checkKnowledgeFreshnessFromIndex as a, renderFreshnessResult as c, smrtReview as d, checkKnowledgeFreshness as i, renderKnowledgeIndexMarkdown as l, buildKnowledgeIndex as n, diffKnowledgeIndex as o, buildReviewContext as r, packageDocPaths as s, buildArchitectureContext as t, smrtArchitecture as u };
+export { checkKnowledgeFreshnessFromIndex as a, renderFreshnessResult as c, smrtReview as d, REVIEW_SKILL_NAME as f, checkKnowledgeFreshness as i, renderKnowledgeIndexMarkdown as l, buildKnowledgeIndex as n, diffKnowledgeIndex as o, TOOLS as p, buildReviewContext as r, packageDocPaths as s, buildArchitectureContext as t, smrtArchitecture as u };
 
-//# sourceMappingURL=knowledge-CCX7oQzQ.js.map
+//# sourceMappingURL=knowledge-A7-gIjW4.js.map