coalesce-transform-mcp 0.1.0

package/dist/services/policies/sql-override.d.ts

@@ -0,0 +1,7 @@
+export type SqlOverridePolicySanitizationResult = {
+    nodeDefinition: Record<string, unknown>;
+    warnings: string[];
+};
+export declare function filterSqlOverrideControls(values: string[]): string[];
+export declare function sanitizeNodeDefinitionSqlOverridePolicy(nodeDefinition: Record<string, unknown>): SqlOverridePolicySanitizationResult;
+export declare function assertNoSqlOverridePayload(value: unknown, context: string): void;

package/dist/services/policies/sql-override.js

@@ -0,0 +1,109 @@
+import { isPlainObject } from "../../utils.js";
+const SQL_OVERRIDE_CONTROL_TYPE = "overrideSQLToggle";
+function cloneValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function filterSqlOverrideControls(values) {
+    return values.filter((value) => value !== SQL_OVERRIDE_CONTROL_TYPE);
+}
+export function sanitizeNodeDefinitionSqlOverridePolicy(nodeDefinition) {
+    const cloned = cloneValue(nodeDefinition);
+    let removedControlCount = 0;
+    let rewrittenExpressionCount = 0;
+    if (Array.isArray(cloned.config)) {
+        cloned.config = cloned.config.flatMap((group) => {
+            if (!isPlainObject(group)) {
+                return [];
+            }
+            const items = Array.isArray(group.items)
+                ? group.items.filter((item) => {
+                    if (!isPlainObject(item)) {
+                        return false;
+                    }
+                    if (item.type === SQL_OVERRIDE_CONTROL_TYPE) {
+                        removedControlCount += 1;
+                        return false;
+                    }
+                    return true;
+                })
+                : [];
+            if (items.length === 0) {
+                return [];
+            }
+            return [{ ...group, items }];
+        });
+    }
+    function sanitizeValue(value) {
+        if (Array.isArray(value)) {
+            return value.map((entry) => sanitizeValue(entry));
+        }
+        if (!isPlainObject(value)) {
+            return value;
+        }
+        const sanitized = {};
+        for (const [key, entryValue] of Object.entries(value)) {
+            if ((key === "enableIf" || key === "disableIf") &&
+                typeof entryValue === "string") {
+                const rewritten = entryValue.replace(/node\.override\.[A-Za-z0-9_.]+/gu, "false");
+                if (rewritten !== entryValue) {
+                    rewrittenExpressionCount += 1;
+                }
+                sanitized[key] = rewritten;
+                continue;
+            }
+            sanitized[key] = sanitizeValue(entryValue);
+        }
+        return sanitized;
+    }
+    const sanitizedDefinition = sanitizeValue(cloned);
+    const warnings = [];
+    if (removedControlCount > 0) {
+        warnings.push(`Removed ${removedControlCount} SQL override control(s) from the returned node definition because SQL override is disallowed for this project.`);
+    }
+    if (rewrittenExpressionCount > 0) {
+        warnings.push(`Rewrote ${rewrittenExpressionCount} conditional expression(s) that referenced node.override.* so returned definitions behave as if SQL override is disabled.`);
+    }
+    return {
+        nodeDefinition: sanitizedDefinition,
+        warnings,
+    };
+}
+function formatPathSegment(segment) {
+    return /^\[\d+\]$/u.test(segment) ? segment : `.${segment}`;
+}
+function formatPath(segments) {
+    if (segments.length === 0) {
+        return "<root>";
+    }
+    return segments.reduce((path, segment, index) => {
+        if (index === 0 && !/^\[\d+\]$/u.test(segment)) {
+            return segment;
+        }
+        return `${path}${formatPathSegment(segment)}`;
+    }, "");
+}
+function collectSqlOverridePaths(value, pathSegments = []) {
+    if (Array.isArray(value)) {
+        return value.flatMap((entry, index) => collectSqlOverridePaths(entry, [...pathSegments, `[${index}]`]));
+    }
+    if (!isPlainObject(value)) {
+        return [];
+    }
+    const matches = [];
+    for (const [key, entryValue] of Object.entries(value)) {
+        const nextPath = [...pathSegments, key];
+        if (key === "overrideSQL" || key === "override") {
+            matches.push(formatPath(nextPath));
+            continue;
+        }
+        matches.push(...collectSqlOverridePaths(entryValue, nextPath));
+    }
+    return matches;
+}
+export function assertNoSqlOverridePayload(value, context) {
+    const offendingPaths = Array.from(new Set(collectSqlOverridePaths(value)));
+    if (offendingPaths.length === 0) {
+        return;
+    }
+    throw new Error(`${context} cannot set SQL override fields. Remove ${offendingPaths.join(", ")}. SQL override is intentionally disallowed in this project.`);
+}

package/dist/services/repo/operations.d.ts

@@ -0,0 +1,6 @@
+export interface RepoNodeTypeDefinition {
+    nodeDefinition: Record<string, unknown> | null;
+    resolvedNodeType: string;
+    warnings: string[];
+}
+export declare function getRepoNodeTypeDefinition(repoPath: string, nodeType: string): Promise<RepoNodeTypeDefinition>;

package/dist/services/repo/operations.js

@@ -0,0 +1,10 @@
+import { parseRepo, resolveRepoNodeType, } from "./parser.js";
+export async function getRepoNodeTypeDefinition(repoPath, nodeType) {
+    const parsedRepo = parseRepo(repoPath);
+    const resolution = resolveRepoNodeType(parsedRepo, nodeType);
+    return {
+        nodeDefinition: resolution.nodeTypeRecord.nodeDefinition,
+        resolvedNodeType: resolution.resolvedNodeType,
+        warnings: resolution.nodeTypeRecord.warnings,
+    };
+}

package/dist/services/repo/parser.d.ts

@@ -0,0 +1,70 @@
+export type RepoOuterDefinition = {
+    fileVersion: unknown;
+    id: string | null;
+    isDisabled: boolean | null;
+    name: string | null;
+    type: string | null;
+    inputMode: string | null;
+};
+export type RepoNodeTypeRecord = {
+    dirName: string;
+    dirPath: string;
+    definitionPath: string;
+    createPath: string | null;
+    runPath: string | null;
+    outerDefinition: RepoOuterDefinition;
+    nodeMetadataSpec: string | null;
+    nodeDefinition: Record<string, unknown> | null;
+    parseError: string | null;
+    warnings: string[];
+};
+export type RepoPackageRecord = {
+    alias: string;
+    aliasSource: "name" | "filename";
+    packageFilePath: string;
+    packageID: string | null;
+    releaseID: string | null;
+    packageVariables: string | null;
+    enabledNodeTypeIDs: string[];
+    resolvedDefinitionIDs: string[];
+    missingDefinitionIDs: string[];
+    ambiguousDefinitionIDs: string[];
+    usageByNodeTypeID: Record<string, number>;
+    usageCount: number;
+    warnings: string[];
+};
+export type ParsedRepoSummary = {
+    repoPath: string;
+    resolvedRepoPath: string;
+    packageCount: number;
+    uniquePackageAliasCount: number;
+    nodeTypeDefinitionCount: number;
+    uniqueNodeTypeIDCount: number;
+    nodeCount: number;
+    warnings: string[];
+};
+export type ParsedRepo = {
+    summary: ParsedRepoSummary;
+    packages: RepoPackageRecord[];
+    nodeTypes: RepoNodeTypeRecord[];
+    usageCounts: Record<string, number>;
+    packagesByAlias: Map<string, RepoPackageRecord[]>;
+    nodeTypesByID: Map<string, RepoNodeTypeRecord[]>;
+};
+export type RepoNodeTypeResolution = {
+    resolutionKind: "direct";
+    requestedNodeType: string;
+    resolvedNodeType: string;
+    usageCount: number;
+    nodeTypeRecord: RepoNodeTypeRecord;
+} | {
+    resolutionKind: "package";
+    requestedNodeType: string;
+    resolvedNodeType: string;
+    packageAlias: string;
+    packageRecord: RepoPackageRecord;
+    usageCount: number;
+    nodeTypeRecord: RepoNodeTypeRecord;
+};
+export declare function parseRepo(repoPath: string): ParsedRepo;
+export declare function resolveRepoNodeType(parsedRepo: ParsedRepo, requestedNodeType: string): RepoNodeTypeResolution;

package/dist/services/repo/parser.js

@@ -0,0 +1,365 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import YAML from "yaml";
+import { isPlainObject } from "../../utils.js";
+function getScalarString(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return String(value);
+    }
+    return null;
+}
+function compareStrings(left, right) {
+    return left.localeCompare(right, undefined, {
+        numeric: true,
+        sensitivity: "case",
+    });
+}
+function readYamlFile(filePath) {
+    return YAML.parse(readFileSync(filePath, "utf8"));
+}
+function listYamlFiles(dirPath) {
+    if (!existsSync(dirPath)) {
+        return [];
+    }
+    return readdirSync(dirPath, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".yml"))
+        .map((entry) => join(dirPath, entry.name))
+        .sort(compareStrings);
+}
+function normalizeRepoPath(repoPath) {
+    const absolutePath = resolve(repoPath);
+    if (!existsSync(absolutePath)) {
+        throw new Error("Repo path does not exist. Check the provided path or COALESCE_REPO_PATH environment variable.");
+    }
+    const stats = statSync(absolutePath);
+    if (!stats.isDirectory()) {
+        throw new Error("Repo path is not a directory. Expected a Coalesce repo directory containing a nodeTypes/ subdirectory.");
+    }
+    const resolvedRepoPath = realpathSync(absolutePath);
+    const nodeTypesDir = join(resolvedRepoPath, "nodeTypes");
+    if (!existsSync(nodeTypesDir) || !statSync(nodeTypesDir).isDirectory()) {
+        throw new Error("Invalid repo path: missing nodeTypes/ subdirectory. " +
+            "Expected a Coalesce repo directory containing nodeTypes/.");
+    }
+    return resolvedRepoPath;
+}
+function buildOuterDefinition(parsed) {
+    return {
+        fileVersion: Object.prototype.hasOwnProperty.call(parsed, "fileVersion")
+            ? parsed.fileVersion
+            : null,
+        id: getScalarString(parsed.id),
+        isDisabled: typeof parsed.isDisabled === "boolean" ? parsed.isDisabled : null,
+        name: getScalarString(parsed.name),
+        type: getScalarString(parsed.type),
+        inputMode: getScalarString(parsed.inputMode),
+    };
+}
+function loadRepoNodeTypes(resolvedRepoPath, warnings) {
+    const nodeTypesDir = join(resolvedRepoPath, "nodeTypes");
+    return readdirSync(nodeTypesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort(compareStrings)
+        .flatMap((dirName) => {
+        const dirPath = join(nodeTypesDir, dirName);
+        const definitionPath = join(dirPath, "definition.yml");
+        const createPath = join(dirPath, "create.sql.j2");
+        const runPath = join(dirPath, "run.sql.j2");
+        if (!existsSync(definitionPath)) {
+            warnings.push(`Skipping node type directory without definition.yml: ${dirPath}`);
+            return [];
+        }
+        try {
+            const parsed = readYamlFile(definitionPath);
+            if (!isPlainObject(parsed)) {
+                warnings.push(`Skipping node type definition that did not parse to an object: ${definitionPath}`);
+                return [];
+            }
+            const metadata = isPlainObject(parsed.metadata) ? parsed.metadata : undefined;
+            const nodeMetadataSpec = metadata && typeof metadata.nodeMetadataSpec === "string"
+                ? metadata.nodeMetadataSpec
+                : null;
+            let nodeDefinition = null;
+            let parseError = null;
+            const recordWarnings = [];
+            if (!nodeMetadataSpec) {
+                recordWarnings.push(`Missing metadata.nodeMetadataSpec in ${definitionPath}`);
+            }
+            else {
+                try {
+                    const parsedNodeDefinition = YAML.parse(nodeMetadataSpec);
+                    if (!isPlainObject(parsedNodeDefinition)) {
+                        throw new Error("Parsed nodeMetadataSpec was not an object");
+                    }
+                    nodeDefinition = parsedNodeDefinition;
+                }
+                catch (error) {
+                    parseError = error instanceof Error ? error.message : String(error);
+                    recordWarnings.push(`Unable to parse metadata.nodeMetadataSpec in ${definitionPath}: ${parseError}`);
+                }
+            }
+            if (!existsSync(createPath)) {
+                recordWarnings.push(`Missing create.sql.j2 for ${definitionPath}`);
+            }
+            if (!existsSync(runPath)) {
+                recordWarnings.push(`Missing run.sql.j2 for ${definitionPath}`);
+            }
+            return [
+                {
+                    dirName,
+                    dirPath,
+                    definitionPath,
+                    createPath: existsSync(createPath) ? createPath : null,
+                    runPath: existsSync(runPath) ? runPath : null,
+                    outerDefinition: buildOuterDefinition(parsed),
+                    nodeMetadataSpec,
+                    nodeDefinition,
+                    parseError,
+                    warnings: recordWarnings,
+                },
+            ];
+        }
+        catch (error) {
+            warnings.push(`Skipping unreadable node type definition ${definitionPath}: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    });
+}
+function buildNodeTypesByID(nodeTypes) {
+    const nodeTypesByID = new Map();
+    for (const nodeType of nodeTypes) {
+        const id = nodeType.outerDefinition.id;
+        if (!id) {
+            continue;
+        }
+        const existing = nodeTypesByID.get(id) ?? [];
+        existing.push(nodeType);
+        nodeTypesByID.set(id, existing);
+    }
+    return nodeTypesByID;
+}
+function loadUsageCounts(resolvedRepoPath, warnings) {
+    const nodesDir = join(resolvedRepoPath, "nodes");
+    if (!existsSync(nodesDir) || !statSync(nodesDir).isDirectory()) {
+        warnings.push(`Repo ${resolvedRepoPath} is missing nodes/; usage counts are unavailable.`);
+        return { nodeCount: 0, usageCounts: {} };
+    }
+    const usageCounts = {};
+    let nodeCount = 0;
+    for (const filePath of listYamlFiles(nodesDir)) {
+        try {
+            const parsed = readYamlFile(filePath);
+            if (!isPlainObject(parsed)) {
+                warnings.push(`Skipping node file that did not parse to an object: ${filePath}`);
+                continue;
+            }
+            nodeCount += 1;
+            const operation = isPlainObject(parsed.operation) ? parsed.operation : undefined;
+            const sqlType = getScalarString(operation?.sqlType);
+            if (!sqlType) {
+                continue;
+            }
+            usageCounts[sqlType] = (usageCounts[sqlType] ?? 0) + 1;
+        }
+        catch (error) {
+            warnings.push(`Skipping unreadable node file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { nodeCount, usageCounts };
+}
+function loadPackages(resolvedRepoPath, nodeTypesByID, usageCounts, warnings) {
+    const packagesDir = join(resolvedRepoPath, "packages");
+    if (!existsSync(packagesDir) || !statSync(packagesDir).isDirectory()) {
+        warnings.push(`Repo ${resolvedRepoPath} is missing packages/; package-backed discovery is unavailable.`);
+        return [];
+    }
+    return listYamlFiles(packagesDir).flatMap((packageFilePath) => {
+        try {
+            const parsed = readYamlFile(packageFilePath);
+            if (!isPlainObject(parsed)) {
+                warnings.push(`Skipping package file that did not parse to an object: ${packageFilePath}`);
+                return [];
+            }
+            const parsedAlias = getScalarString(parsed.name);
+            const aliasSource = parsedAlias ? "name" : "filename";
+            const alias = parsedAlias ?? basename(packageFilePath, ".yml");
+            const config = isPlainObject(parsed.config) ? parsed.config : undefined;
+            const entities = isPlainObject(config?.entities) ? config.entities : undefined;
+            const nodeTypes = isPlainObject(entities?.nodeTypes) ? entities.nodeTypes : {};
+            const enabledNodeTypeIDs = Object.entries(nodeTypes)
+                .filter(([, value]) => !(isPlainObject(value) && value.isDisabled === true))
+                .map(([id]) => id)
+                .sort(compareStrings);
+            const resolvedDefinitionIDs = [];
+            const missingDefinitionIDs = [];
+            const ambiguousDefinitionIDs = [];
+            const usageByNodeTypeID = {};
+            for (const id of enabledNodeTypeIDs) {
+                const matches = nodeTypesByID.get(id) ?? [];
+                if (matches.length === 1) {
+                    resolvedDefinitionIDs.push(id);
+                }
+                else if (matches.length === 0) {
+                    missingDefinitionIDs.push(id);
+                }
+                else {
+                    ambiguousDefinitionIDs.push(id);
+                }
+                usageByNodeTypeID[id] = usageCounts[`${alias}:::${id}`] ?? 0;
+            }
+            const recordWarnings = [];
+            if (!parsedAlias) {
+                recordWarnings.push(`Package ${packageFilePath} is missing name; falling back to filename alias ${alias}.`);
+            }
+            if (missingDefinitionIDs.length > 0) {
+                recordWarnings.push(`Package alias ${alias} enables node type IDs without committed definitions: ${missingDefinitionIDs.join(", ")}.`);
+            }
+            if (ambiguousDefinitionIDs.length > 0) {
+                recordWarnings.push(`Package alias ${alias} enables node type IDs with ambiguous committed definitions: ${ambiguousDefinitionIDs.join(", ")}.`);
+            }
+            return [
+                {
+                    alias,
+                    aliasSource,
+                    packageFilePath,
+                    packageID: getScalarString(parsed.packageID),
+                    releaseID: getScalarString(parsed.releaseID),
+                    packageVariables: getScalarString(config?.packageVariables),
+                    enabledNodeTypeIDs,
+                    resolvedDefinitionIDs,
+                    missingDefinitionIDs,
+                    ambiguousDefinitionIDs,
+                    usageByNodeTypeID,
+                    usageCount: Object.values(usageByNodeTypeID).reduce((sum, value) => sum + value, 0),
+                    warnings: recordWarnings,
+                },
+            ];
+        }
+        catch (error) {
+            warnings.push(`Skipping unreadable package file ${packageFilePath}: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    });
+}
+function buildPackagesByAlias(packages) {
+    const packagesByAlias = new Map();
+    for (const record of packages) {
+        const existing = packagesByAlias.get(record.alias) ?? [];
+        existing.push(record);
+        packagesByAlias.set(record.alias, existing);
+    }
+    return packagesByAlias;
+}
+function collectAmbiguityWarnings(packagesByAlias, nodeTypesByID) {
+    const warnings = [];
+    for (const [alias, matches] of packagesByAlias.entries()) {
+        if (matches.length < 2) {
+            continue;
+        }
+        warnings.push(`Multiple package manifests share alias ${alias}: ${matches
+            .map((match) => match.packageFilePath)
+            .join(", ")}.`);
+    }
+    for (const [id, matches] of nodeTypesByID.entries()) {
+        if (matches.length < 2) {
+            continue;
+        }
+        warnings.push(`Multiple committed nodeTypes share id ${id}: ${matches
+            .map((match) => match.definitionPath)
+            .join(", ")}.`);
+    }
+    return warnings.sort(compareStrings);
+}
+export function parseRepo(repoPath) {
+    const resolvedRepoPath = normalizeRepoPath(repoPath);
+    const warnings = [];
+    const nodeTypes = loadRepoNodeTypes(resolvedRepoPath, warnings);
+    const nodeTypesByID = buildNodeTypesByID(nodeTypes);
+    const { nodeCount, usageCounts } = loadUsageCounts(resolvedRepoPath, warnings);
+    const packages = loadPackages(resolvedRepoPath, nodeTypesByID, usageCounts, warnings);
+    const packagesByAlias = buildPackagesByAlias(packages);
+    warnings.push(...collectAmbiguityWarnings(packagesByAlias, nodeTypesByID));
+    return {
+        summary: {
+            repoPath,
+            resolvedRepoPath,
+            packageCount: packages.length,
+            uniquePackageAliasCount: packagesByAlias.size,
+            nodeTypeDefinitionCount: nodeTypes.length,
+            uniqueNodeTypeIDCount: nodeTypesByID.size,
+            nodeCount,
+            warnings: Array.from(new Set(warnings)),
+        },
+        packages,
+        nodeTypes,
+        usageCounts,
+        packagesByAlias,
+        nodeTypesByID,
+    };
+}
+function buildRepoResolutionError(parsedRepo, requestedNodeType, detail) {
+    return new Error(`Repo-backed definition could not be resolved for ${requestedNodeType} in ${parsedRepo.summary.resolvedRepoPath}. ${detail} Use the corpus tools (search-node-type-variants, get-node-type-variant, or generate-set-workspace-node-template-from-variant) as the next step.`);
+}
+export function resolveRepoNodeType(parsedRepo, requestedNodeType) {
+    const delimiterIndex = requestedNodeType.indexOf(":::");
+    if (delimiterIndex !== -1) {
+        const packageAlias = requestedNodeType.slice(0, delimiterIndex);
+        const definitionID = requestedNodeType.slice(delimiterIndex + 3);
+        if (!packageAlias || !definitionID) {
+            throw buildRepoResolutionError(parsedRepo, requestedNodeType, "Package-backed identifiers must use the exact alias:::id format.");
+        }
+        const packageMatches = parsedRepo.packagesByAlias.get(packageAlias) ?? [];
+        if (packageMatches.length === 0) {
+            throw buildRepoResolutionError(parsedRepo, requestedNodeType, `No committed package alias ${packageAlias} was found under packages/.`);
+        }
+        if (packageMatches.length > 1) {
+            throw buildRepoResolutionError(parsedRepo, requestedNodeType, `Package alias ${packageAlias} is ambiguous across ${packageMatches
+                .map((match) => match.packageFilePath)
+                .join(", ")}.`);
+        }
+        const packageRecord = packageMatches[0];
+        if (!packageRecord.enabledNodeTypeIDs.includes(definitionID)) {
+            throw buildRepoResolutionError(parsedRepo, requestedNodeType, `Package alias ${packageAlias} does not enable node type ID ${definitionID}.`);
+        }
+        const nodeTypeMatches = parsedRepo.nodeTypesByID.get(definitionID) ?? [];
+        if (nodeTypeMatches.length === 0) {
+            throw buildRepoResolutionError(parsedRepo, requestedNodeType, `Package alias ${packageAlias} enables ID ${definitionID}, but no committed nodeTypes definition with outer id ${definitionID} was found.`);
+        }
+        if (nodeTypeMatches.length > 1) {
+            throw buildRepoResolutionError(parsedRepo, requestedNodeType, `Package alias ${packageAlias} maps to multiple committed definitions for outer id ${definitionID}: ${nodeTypeMatches
+                .map((match) => match.definitionPath)
+                .join(", ")}.`);
+        }
+        return {
+            resolutionKind: "package",
+            requestedNodeType,
+            resolvedNodeType: `${packageAlias}:::${definitionID}`,
+            packageAlias,
+            packageRecord,
+            usageCount: parsedRepo.usageCounts[`${packageAlias}:::${definitionID}`] ?? 0,
+            nodeTypeRecord: nodeTypeMatches[0],
+        };
+    }
+    const nodeTypeMatches = parsedRepo.nodeTypesByID.get(requestedNodeType) ?? [];
+    if (nodeTypeMatches.length === 0) {
+        throw buildRepoResolutionError(parsedRepo, requestedNodeType, `No committed nodeTypes definition with outer id ${requestedNodeType} was found.`);
+    }
+    if (nodeTypeMatches.length > 1) {
+        throw buildRepoResolutionError(parsedRepo, requestedNodeType, `Multiple committed nodeTypes definitions share outer id ${requestedNodeType}: ${nodeTypeMatches
+            .map((match) => match.definitionPath)
+            .join(", ")}.`);
+    }
+    return {
+        resolutionKind: "direct",
+        requestedNodeType,
+        resolvedNodeType: requestedNodeType,
+        usageCount: parsedRepo.usageCounts[requestedNodeType] ?? 0,
+        nodeTypeRecord: nodeTypeMatches[0],
+    };
+}

package/dist/services/repo/path.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveOptionalRepoPathInput(repoPath?: string): string | undefined;
+export declare function resolveRepoPathInput(repoPath?: string): string;

package/dist/services/repo/path.js

@@ -0,0 +1,58 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+/**
+ * Validates that a path is a legitimate Coalesce repo directory.
+ *
+ * Security boundary: repoPath originates from tool input (LLM-controlled) or
+ * the COALESCE_REPO_PATH env var. We resolve symlinks, verify it is a real
+ * directory, and require the Coalesce-specific nodeTypes/ subdirectory before
+ * allowing any filesystem reads downstream.
+ *
+ * Error messages intentionally omit the resolved path to avoid leaking
+ * filesystem layout through MCP tool responses.
+ */
+function validateRepoPath(rawPath) {
+    const absolutePath = resolve(rawPath);
+    if (!existsSync(absolutePath)) {
+        throw new Error("repoPath does not exist. Check the provided path or COALESCE_REPO_PATH environment variable.");
+    }
+    const stats = statSync(absolutePath);
+    if (!stats.isDirectory()) {
+        throw new Error("repoPath is not a directory. Expected a Coalesce repo directory containing a nodeTypes/ subdirectory.");
+    }
+    // Resolve symlinks to get the canonical path
+    const resolvedPath = realpathSync(absolutePath);
+    // Structural validation: a Coalesce repo must have a nodeTypes/ directory
+    const nodeTypesDir = join(resolvedPath, "nodeTypes");
+    if (!existsSync(nodeTypesDir) || !statSync(nodeTypesDir).isDirectory()) {
+        throw new Error("repoPath is not a valid Coalesce repo: missing nodeTypes/ subdirectory. " +
+            "Expected a directory containing nodeTypes/, typically a cloned Coalesce project repo.");
+    }
+    return resolvedPath;
+}
+function getConfiguredRepoPathInput(repoPath) {
+    const explicitRepoPath = typeof repoPath === "string" && repoPath.trim().length > 0
+        ? repoPath
+        : undefined;
+    if (explicitRepoPath) {
+        return explicitRepoPath;
+    }
+    const envRepoPath = process.env.COALESCE_REPO_PATH;
+    if (typeof envRepoPath === "string" && envRepoPath.trim().length > 0) {
+        return envRepoPath;
+    }
+    return undefined;
+}
+export function resolveOptionalRepoPathInput(repoPath) {
+    // Optional callers handle repo parse failures themselves and should degrade
+    // gracefully to corpus- or warning-based behavior when the configured path
+    // is stale or invalid.
+    return getConfiguredRepoPathInput(repoPath);
+}
+export function resolveRepoPathInput(repoPath) {
+    const configuredRepoPath = getConfiguredRepoPathInput(repoPath);
+    if (configuredRepoPath) {
+        return validateRepoPath(configuredRepoPath);
+    }
+    throw new Error("repoPath is required for repo-backed tools. Provide repoPath explicitly or set COALESCE_REPO_PATH.");
+}

package/dist/services/templates/nodes.d.ts

@@ -0,0 +1,50 @@
+export type NodeDefinitionTemplateOptions = {
+    nodeName?: string;
+    nodeType?: string;
+    locationName?: string;
+    database?: string;
+    schema?: string;
+};
+export type NodeDefinitionFieldMapping = {
+    groupIndex: number;
+    itemIndex: number;
+    groupName: string | null;
+    itemType: string | null;
+    displayName: string | null;
+    attributeName: string | null;
+    targetPath: string | null;
+    defaultValue: unknown;
+    enableIf: string | null;
+    note: string;
+};
+export type GeneratedNodeDefinitionTemplate = {
+    definitionSummary: {
+        capitalized: string | null;
+        short: string | null;
+        plural: string | null;
+        tagColor: string | null;
+        configGroupCount: number;
+        configItemCount: number;
+    };
+    fieldMappings: NodeDefinitionFieldMapping[];
+    inferredTopLevelFields: Record<string, unknown>;
+    inferredConfig: Record<string, unknown>;
+    setWorkspaceNodeBodyTemplate: Record<string, unknown>;
+    usageGuidance: string[];
+    warnings: string[];
+};
+export type TemplateComparisonResult = {
+    checkedFieldCount: number;
+    matchedFieldCount: number;
+    mismatchedFieldCount: number;
+    missingFieldCount: number;
+    fields: Array<{
+        targetPath: string;
+        inferredDefault: unknown;
+        actualValue: unknown;
+        status: "matched" | "mismatched" | "missing";
+    }>;
+};
+export declare function buildSetWorkspaceNodeTemplateFromDefinition(nodeDefinition: Record<string, unknown>, options?: NodeDefinitionTemplateOptions): GeneratedNodeDefinitionTemplate;
+export declare function compareGeneratedTemplateToWorkspaceNode(generated: GeneratedNodeDefinitionTemplate, workspaceNode: Record<string, unknown>): TemplateComparisonResult;
+export declare function renderYaml(value: unknown): string;