@agiflowai/aicode-utils 1.0.15 → 1.0.17

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
-import * as path$1 from "node:path";
-import path from "node:path";
+import * as path from "node:path";
+import nodePath from "node:path";
 import * as fs from "node:fs/promises";
 import { accessSync, mkdirSync, readFileSync, readFileSync as readFileSync$1, statSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
@@ -84,7 +84,7 @@ async function copy(src, dest) {
 * Move a file or directory
 */
 async function move(src, dest) {
-	await ensureDir(path.dirname(dest));
+	await ensureDir(nodePath.dirname(dest));
 	await fs.rename(src, dest);
 }
 /**
@@ -120,12 +120,12 @@ const cp = fs.cp;
 
 //#endregion
 //#region src/utils/logger.ts
-const logsDir = path$1.join(os.tmpdir(), "scaffold-mcp-logs");
+const logsDir = path.join(os.tmpdir(), "scaffold-mcp-logs");
 const logger = pino({
 	level: process.env.LOG_LEVEL || "debug",
 	timestamp: pino.stdTimeFunctions.isoTime
 }, pino.destination({
-	dest: path$1.join(logsDir, "scaffold-mcp.log"),
+	dest: path.join(logsDir, "scaffold-mcp.log"),
 	mkdir: true,
 	sync: true
 }));
@@ -164,16 +164,41 @@ const log = {
 var TemplatesManagerService = class TemplatesManagerService {
 	static SCAFFOLD_CONFIG_FILE = "scaffold.yaml";
 	static TEMPLATES_FOLDER = "templates";
+	static TOOLKIT_FOLDER = ".toolkit";
+	static SETTINGS_FILE = "settings.yaml";
+	static SETTINGS_LOCAL_FILE = "settings.local.yaml";
 	static TOOLKIT_CONFIG_FILE = "toolkit.yaml";
 	/**
+	* Recursively merge two plain objects. Primitive and array values in `local`
+	* replace those in `base`; plain-object values are merged recursively.
+	*/
+	static deepMerge(base, local) {
+		const result = { ...base };
+		for (const [key, localValue] of Object.entries(local)) {
+			const baseValue = result[key];
+			if (localValue !== null && typeof localValue === "object" && !Array.isArray(localValue) && baseValue !== null && typeof baseValue === "object" && !Array.isArray(baseValue)) result[key] = TemplatesManagerService.deepMerge(baseValue, localValue);
+			else result[key] = localValue;
+		}
+		return result;
+	}
+	/**
+	* Deep-merge two ToolkitConfig objects. Plain-object values are merged
+	* recursively; primitives and arrays in `local` replace those in `base`.
+	* This allows settings.local.yaml to override a single leaf key (e.g.
+	* scaffold-mcp.mcp-serve.fallbackTool) without wiping sibling keys.
+	*/
+	static mergeToolkitConfigs(base, local) {
+		return TemplatesManagerService.deepMerge(base, local);
+	}
+	/**
 	* Find the templates directory by searching upwards from the starting path.
 	*
 	* Algorithm:
 	* 1. Start from the provided path (default: current working directory)
 	* 2. Search upwards to find the workspace root (where .git exists or filesystem root)
-	* 3. Check if toolkit.yaml exists at workspace root
-	*    - If yes, read templatesPath from toolkit.yaml
-	*    - If no, default to 'templates' folder in workspace root
+	* 3. Read toolkit config (checks .toolkit/settings.yaml, then toolkit.yaml)
+	*    - If config has templatesPath, use it
+	*    - If no config, default to 'templates' folder in workspace root
 	* 4. Verify the templates directory exists
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
@@ -181,18 +206,13 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static async findTemplatesPath(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (await pathExists(toolkitConfigPath)) {
-			const yaml$1 = await import("js-yaml");
-			const content = await fs.readFile(toolkitConfigPath, "utf-8");
-			const config = yaml$1.load(content);
-			if (config?.templatesPath) {
-				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
-				if (await pathExists(templatesPath$1)) return templatesPath$1;
-				else return null;
-			}
+		const config = await TemplatesManagerService.readToolkitConfig(startPath);
+		if (config?.templatesPath) {
+			const templatesPath$1 = nodePath.isAbsolute(config.templatesPath) ? config.templatesPath : nodePath.join(workspaceRoot, config.templatesPath);
+			if (await pathExists(templatesPath$1)) return templatesPath$1;
+			return null;
 		}
-		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
+		const templatesPath = nodePath.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
 		if (await pathExists(templatesPath)) return templatesPath;
 		return null;
 	}
@@ -200,12 +220,12 @@ var TemplatesManagerService = class TemplatesManagerService {
 	* Find the workspace root by searching upwards for .git folder
 	*/
 	static async findWorkspaceRoot(startPath) {
-		let currentPath = path.resolve(startPath);
-		const rootPath = path.parse(currentPath).root;
+		let currentPath = nodePath.resolve(startPath);
+		const rootPath = nodePath.parse(currentPath).root;
 		while (true) {
-			if (await pathExists(path.join(currentPath, ".git"))) return currentPath;
+			if (await pathExists(nodePath.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
-			currentPath = path.dirname(currentPath);
+			currentPath = nodePath.dirname(currentPath);
 		}
 	}
 	/**
@@ -217,18 +237,13 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static findTemplatesPathSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (pathExistsSync(toolkitConfigPath)) {
-			const yaml$1 = __require("js-yaml");
-			const content = readFileSync$1(toolkitConfigPath, "utf-8");
-			const config = yaml$1.load(content);
-			if (config?.templatesPath) {
-				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
-				if (pathExistsSync(templatesPath$1)) return templatesPath$1;
-				else return null;
-			}
+		const config = TemplatesManagerService.readToolkitConfigSync(startPath);
+		if (config?.templatesPath) {
+			const templatesPath$1 = nodePath.isAbsolute(config.templatesPath) ? config.templatesPath : nodePath.join(workspaceRoot, config.templatesPath);
+			if (pathExistsSync(templatesPath$1)) return templatesPath$1;
+			return null;
 		}
-		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
+		const templatesPath = nodePath.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
 		if (pathExistsSync(templatesPath)) return templatesPath;
 		return null;
 	}
@@ -236,12 +251,12 @@ var TemplatesManagerService = class TemplatesManagerService {
 	* Find the workspace root synchronously by searching upwards for .git folder
 	*/
 	static findWorkspaceRootSync(startPath) {
-		let currentPath = path.resolve(startPath);
-		const rootPath = path.parse(currentPath).root;
+		let currentPath = nodePath.resolve(startPath);
+		const rootPath = nodePath.parse(currentPath).root;
 		while (true) {
-			if (pathExistsSync(path.join(currentPath, ".git"))) return currentPath;
+			if (pathExistsSync(nodePath.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
-			currentPath = path.dirname(currentPath);
+			currentPath = nodePath.dirname(currentPath);
 		}
 	}
 	/**
@@ -267,44 +282,80 @@ var TemplatesManagerService = class TemplatesManagerService {
 		return TemplatesManagerService.TEMPLATES_FOLDER;
 	}
 	/**
-	* Read toolkit.yaml configuration from workspace root
+	* Read toolkit configuration from workspace root.
+	*
+	* Priority order:
+	* 1. .toolkit/settings.yaml (new location)
+	* 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+	* 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	* @returns The toolkit configuration object or null if not found
 	*/
 	static async readToolkitConfig(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!await pathExists(toolkitConfigPath)) return null;
 		const yaml$1 = await import("js-yaml");
-		const content = await fs.readFile(toolkitConfigPath, "utf-8");
+		const toolkitFolder = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = nodePath.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		const settingsLocalPath = nodePath.join(toolkitFolder, TemplatesManagerService.SETTINGS_LOCAL_FILE);
+		if (await pathExists(settingsPath)) {
+			const baseContent = await fs.readFile(settingsPath, "utf-8");
+			const base = yaml$1.load(baseContent);
+			if (await pathExists(settingsLocalPath)) {
+				const localContent = await fs.readFile(settingsLocalPath, "utf-8");
+				const local = yaml$1.load(localContent);
+				return TemplatesManagerService.mergeToolkitConfigs(base, local);
+			}
+			return base;
+		}
+		const legacyConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!await pathExists(legacyConfigPath)) return null;
+		const content = await fs.readFile(legacyConfigPath, "utf-8");
 		return yaml$1.load(content);
 	}
 	/**
-	* Read toolkit.yaml configuration from workspace root (sync)
+	* Read toolkit configuration from workspace root (sync).
+	*
+	* Priority order:
+	* 1. .toolkit/settings.yaml (new location)
+	* 2. Shallow-merge .toolkit/settings.local.yaml over settings.yaml if present
+	* 3. Fallback to root toolkit.yaml (deprecated, backward-compat)
 	*
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	* @returns The toolkit configuration object or null if not found
 	*/
 	static readToolkitConfigSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!pathExistsSync(toolkitConfigPath)) return null;
 		const yaml$1 = __require("js-yaml");
-		const content = readFileSync$1(toolkitConfigPath, "utf-8");
-		return yaml$1.load(content);
+		const toolkitFolder = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = nodePath.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		const settingsLocalPath = nodePath.join(toolkitFolder, TemplatesManagerService.SETTINGS_LOCAL_FILE);
+		if (pathExistsSync(settingsPath)) {
+			const base = yaml$1.load(readFileSync$1(settingsPath, "utf-8"));
+			if (pathExistsSync(settingsLocalPath)) {
+				const local = yaml$1.load(readFileSync$1(settingsLocalPath, "utf-8"));
+				return TemplatesManagerService.mergeToolkitConfigs(base, local);
+			}
+			return base;
+		}
+		const legacyConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!pathExistsSync(legacyConfigPath)) return null;
+		return yaml$1.load(readFileSync$1(legacyConfigPath, "utf-8"));
 	}
 	/**
-	* Write toolkit.yaml configuration to workspace root
+	* Write toolkit configuration to .toolkit/settings.yaml.
+	* Creates the .toolkit directory if it does not exist.
 	*
 	* @param config - The toolkit configuration to write
 	* @param startPath - The path to start searching from (defaults to process.cwd())
 	*/
 	static async writeToolkitConfig(config, startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		const toolkitFolder = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_FOLDER);
+		const settingsPath = nodePath.join(toolkitFolder, TemplatesManagerService.SETTINGS_FILE);
+		await fs.mkdir(toolkitFolder, { recursive: true });
 		const content = (await import("js-yaml")).dump(config, { indent: 2 });
-		await fs.writeFile(toolkitConfigPath, content, "utf-8");
+		await fs.writeFile(settingsPath, content, "utf-8");
 	}
 	/**
 	* Get the workspace root directory
@@ -373,13 +424,13 @@ var ProjectConfigResolver = class ProjectConfigResolver {
 	*/
 	static async resolveProjectConfig(projectPath, explicitTemplate) {
 		try {
-			const absolutePath = path.resolve(projectPath);
+			const absolutePath = nodePath.resolve(projectPath);
 			if (explicitTemplate) return {
 				type: ProjectType.MONOLITH,
 				sourceTemplate: explicitTemplate,
 				configSource: ConfigSource.TOOLKIT_YAML
 			};
-			const projectJsonPath = path.join(absolutePath, "project.json");
+			const projectJsonPath = nodePath.join(absolutePath, "project.json");
 			if (await pathExists(projectJsonPath)) {
 				const projectJson = await readJson(projectJsonPath);
 				if (projectJson.sourceTemplate && typeof projectJson.sourceTemplate === "string" && projectJson.sourceTemplate.trim()) return {
@@ -470,12 +521,12 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 	* @param sourceTemplate - The template identifier
 	*/
 	static async createProjectJson(projectPath, projectName, sourceTemplate) {
-		const projectJsonPath = path.join(projectPath, "project.json");
+		const projectJsonPath = nodePath.join(projectPath, "project.json");
 		try {
 			let projectJson;
 			if (await pathExists(projectJsonPath)) projectJson = await readJson(projectJsonPath);
 			else {
-				const relativePath = path.relative(projectPath, process.cwd());
+				const relativePath = nodePath.relative(projectPath, process.cwd());
 				projectJson = {
 					name: projectName,
 					$schema: relativePath ? `${relativePath}/node_modules/nx/schemas/project-schema.json` : "node_modules/nx/schemas/project-schema.json",
@@ -527,15 +578,15 @@ var ProjectFinderService = class {
 	* @returns Project configuration or null if not found
 	*/
 	async findProjectForFile(filePath) {
-		const normalizedPath = path.isAbsolute(filePath) ? filePath : path.join(this.workspaceRoot, filePath);
-		let currentDir = path.dirname(normalizedPath);
+		const normalizedPath = nodePath.isAbsolute(filePath) ? filePath : nodePath.join(this.workspaceRoot, filePath);
+		let currentDir = nodePath.dirname(normalizedPath);
 		while (currentDir !== "/" && currentDir.startsWith(this.workspaceRoot)) {
-			const projectJsonPath = path.join(currentDir, "project.json");
+			const projectJsonPath = nodePath.join(currentDir, "project.json");
 			try {
 				const project = await this.loadProjectConfig(projectJsonPath);
 				if (project) return project;
 			} catch {}
-			currentDir = path.dirname(currentDir);
+			currentDir = nodePath.dirname(currentDir);
 		}
 		return null;
 	}
@@ -546,15 +597,15 @@ var ProjectFinderService = class {
 	* @returns Project configuration or null if not found
 	*/
 	findProjectForFileSync(filePath) {
-		const normalizedPath = path.isAbsolute(filePath) ? filePath : path.join(this.workspaceRoot, filePath);
-		let currentDir = path.dirname(normalizedPath);
+		const normalizedPath = nodePath.isAbsolute(filePath) ? filePath : nodePath.join(this.workspaceRoot, filePath);
+		let currentDir = nodePath.dirname(normalizedPath);
 		while (currentDir !== "/" && currentDir.startsWith(this.workspaceRoot)) {
-			const projectJsonPath = path.join(currentDir, "project.json");
+			const projectJsonPath = nodePath.join(currentDir, "project.json");
 			try {
 				const project = this.loadProjectConfigSync(projectJsonPath);
 				if (project) return project;
 			} catch {}
-			currentDir = path.dirname(currentDir);
+			currentDir = nodePath.dirname(currentDir);
 		}
 		return null;
 	}
@@ -567,8 +618,8 @@ var ProjectFinderService = class {
 			const content = await fs.readFile(projectJsonPath, "utf-8");
 			const config = JSON.parse(content);
 			const projectConfig = {
-				name: config.name || path.basename(path.dirname(projectJsonPath)),
-				root: path.dirname(projectJsonPath),
+				name: config.name || nodePath.basename(nodePath.dirname(projectJsonPath)),
+				root: nodePath.dirname(projectJsonPath),
 				sourceTemplate: config.sourceTemplate,
 				projectType: config.projectType
 			};
@@ -587,8 +638,8 @@ var ProjectFinderService = class {
 			const content = readFileSync$1(projectJsonPath, "utf-8");
 			const config = JSON.parse(content);
 			const projectConfig = {
-				name: config.name || path.basename(path.dirname(projectJsonPath)),
-				root: path.dirname(projectJsonPath),
+				name: config.name || nodePath.basename(nodePath.dirname(projectJsonPath)),
+				root: nodePath.dirname(projectJsonPath),
 				sourceTemplate: config.sourceTemplate,
 				projectType: config.projectType
 			};
@@ -648,7 +699,7 @@ var ScaffoldProcessingService = class {
 	* Now supports tracking existing files separately from created files
 	*/
 	async copyAndProcess(sourcePath, targetPath, variables, createdFiles, existingFiles) {
-		await this.fileSystem.ensureDir(path.dirname(targetPath));
+		await this.fileSystem.ensureDir(nodePath.dirname(targetPath));
 		if (await this.fileSystem.pathExists(targetPath) && existingFiles) {
 			await this.trackExistingFiles(targetPath, existingFiles);
 			return;
@@ -670,7 +721,7 @@ var ScaffoldProcessingService = class {
 		}
 		for (const item of items) {
 			if (!item) continue;
-			const itemPath = path.join(dirPath, item);
+			const itemPath = nodePath.join(dirPath, item);
 			try {
 				const stat$1 = await this.fileSystem.stat(itemPath);
 				if (stat$1.isDirectory()) await this.trackCreatedFilesRecursive(itemPath, createdFiles);
@@ -693,7 +744,7 @@ var ScaffoldProcessingService = class {
 		}
 		for (const item of items) {
 			if (!item) continue;
-			const itemPath = path.join(dirPath, item);
+			const itemPath = nodePath.join(dirPath, item);
 			try {
 				const stat$1 = await this.fileSystem.stat(itemPath);
 				if (stat$1.isDirectory()) await this.trackExistingFilesRecursive(itemPath, existingFiles);
@@ -820,12 +871,12 @@ async function gitInit(projectPath) {
 * }
 */
 async function findWorkspaceRoot(startPath = process.cwd()) {
-	let currentPath = path.resolve(startPath);
-	const rootPath = path.parse(currentPath).root;
+	let currentPath = nodePath.resolve(startPath);
+	const rootPath = nodePath.parse(currentPath).root;
 	while (true) {
-		if (await pathExists(path.join(currentPath, ".git"))) return currentPath;
+		if (await pathExists(nodePath.join(currentPath, ".git"))) return currentPath;
 		if (currentPath === rootPath) return null;
-		currentPath = path.dirname(currentPath);
+		currentPath = nodePath.dirname(currentPath);
 	}
 }
 /**
@@ -907,7 +958,7 @@ async function cloneSubdirectory(repoUrl, branch, subdirectory, targetFolder) {
 			"core.sparseCheckout",
 			"true"
 		], tempFolder);
-		await writeFile(path.join(tempFolder, ".git", "info", "sparse-checkout"), `${subdirectory}\n`);
+		await writeFile(nodePath.join(tempFolder, ".git", "info", "sparse-checkout"), `${subdirectory}\n`);
 		await execGit([
 			"pull",
 			"--depth=1",
@@ -915,7 +966,7 @@ async function cloneSubdirectory(repoUrl, branch, subdirectory, targetFolder) {
 			"--",
 			branch
 		], tempFolder);
-		const sourceDir = path.join(tempFolder, subdirectory);
+		const sourceDir = nodePath.join(tempFolder, subdirectory);
 		if (!await pathExists(sourceDir)) throw new Error(`Subdirectory '${subdirectory}' not found in repository at branch '${branch}'`);
 		if (await pathExists(targetFolder)) throw new Error(`Target folder already exists: ${targetFolder}`);
 		await move(sourceDir, targetFolder);
@@ -942,7 +993,7 @@ async function cloneRepository(repoUrl, targetFolder) {
 		repoUrl,
 		targetFolder
 	]);
-	const gitFolder = path.join(targetFolder, ".git");
+	const gitFolder = nodePath.join(targetFolder, ".git");
 	if (await pathExists(gitFolder)) await remove(gitFolder);
 }
 /**
@@ -1159,7 +1210,7 @@ const MONOREPO_INDICATOR_FILES = [
 */
 async function detectProjectType(workspaceRoot) {
 	const indicators = [];
-	const toolkitYamlPath = path.join(workspaceRoot, "toolkit.yaml");
+	const toolkitYamlPath = nodePath.join(workspaceRoot, "toolkit.yaml");
 	if (await pathExists(toolkitYamlPath)) try {
 		const content = await fs.readFile(toolkitYamlPath, "utf-8");
 		const config = yaml.load(content);
@@ -1171,14 +1222,14 @@ async function detectProjectType(workspaceRoot) {
 			};
 		}
 	} catch {}
-	for (const filename of MONOREPO_INDICATOR_FILES) if (await pathExists(path.join(workspaceRoot, filename))) {
+	for (const filename of MONOREPO_INDICATOR_FILES) if (await pathExists(nodePath.join(workspaceRoot, filename))) {
 		indicators.push(`${filename} found`);
 		return {
 			projectType: ProjectType.MONOREPO,
 			indicators
 		};
 	}
-	const packageJsonPath = path.join(workspaceRoot, "package.json");
+	const packageJsonPath = nodePath.join(workspaceRoot, "package.json");
 	if (await pathExists(packageJsonPath)) try {
 		if ((await readJson(packageJsonPath)).workspaces) {
 			indicators.push("package.json with workspaces found");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/aicode-utils",
   "description": "Shared utilities and types for AI-powered code generation, scaffolding, and analysis",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {