@agiflowai/aicode-utils 1.0.2 → 1.0.4

package/README.md

@@ -360,7 +360,6 @@ await TemplatesManagerService.writeToolkitConfig({
 
 **Dependencies**:
 - `chalk` - Terminal colors and styling
-- `fs-extra` - Enhanced file system operations
 - `js-yaml` - YAML parsing for toolkit.yaml
 - `pino` - Structured logging
 

package/dist/index.cjs

@@ -23,8 +23,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let node_path = require("node:path");
 node_path = __toESM(node_path);
-let fs_extra = require("fs-extra");
-fs_extra = __toESM(fs_extra);
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = __toESM(node_fs_promises);
+let node_fs = require("node:fs");
 let node_os = require("node:os");
 node_os = __toESM(node_os);
 let pino = require("pino");
@@ -50,6 +51,114 @@ const ConfigSource = {
 	TOOLKIT_YAML: "toolkit.yaml"
 };
 
+//#endregion
+//#region src/utils/fsHelpers.ts
+/**
+* Native FS Helper Functions
+*
+* Provides fs-extra-like API using native node:fs/promises
+* to avoid ESM compatibility issues with fs-extra
+*/
+/**
+* Check if a file or directory exists
+*/
+async function pathExists(filePath) {
+	try {
+		await node_fs_promises.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if a file or directory exists (sync)
+*/
+function pathExistsSync(filePath) {
+	try {
+		(0, node_fs.accessSync)(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Ensure a directory exists, creating it recursively if needed
+*/
+async function ensureDir(dirPath) {
+	await node_fs_promises.mkdir(dirPath, { recursive: true });
+}
+/**
+* Ensure a directory exists (sync), creating it recursively if needed
+*/
+function ensureDirSync(dirPath) {
+	(0, node_fs.mkdirSync)(dirPath, { recursive: true });
+}
+/**
+* Remove a file or directory recursively
+*/
+async function remove(filePath) {
+	await node_fs_promises.rm(filePath, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Copy a file or directory recursively
+*/
+async function copy(src, dest) {
+	await node_fs_promises.cp(src, dest, { recursive: true });
+}
+/**
+* Move a file or directory
+*/
+async function move(src, dest) {
+	await ensureDir(node_path.default.dirname(dest));
+	await node_fs_promises.rename(src, dest);
+}
+/**
+* Read and parse a JSON file
+*/
+async function readJson(filePath) {
+	const content = await node_fs_promises.readFile(filePath, "utf-8");
+	return JSON.parse(content);
+}
+/**
+* Read and parse a JSON file (sync)
+*/
+function readJsonSync(filePath) {
+	const content = (0, node_fs.readFileSync)(filePath, "utf-8");
+	return JSON.parse(content);
+}
+/**
+* Write an object as JSON to a file
+*/
+async function writeJson(filePath, data, options) {
+	const content = JSON.stringify(data, null, options?.spaces ?? 2);
+	await node_fs_promises.writeFile(filePath, `${content}\n`, "utf-8");
+}
+/**
+* Write an object as JSON to a file (sync)
+*/
+function writeJsonSync(filePath, data, options) {
+	(0, node_fs.writeFileSync)(filePath, `${JSON.stringify(data, null, options?.spaces ?? 2)}\n`, "utf-8");
+}
+/**
+* Output file - writes content ensuring directory exists
+*/
+async function outputFile(filePath, content) {
+	await ensureDir(node_path.default.dirname(filePath));
+	await node_fs_promises.writeFile(filePath, content, "utf-8");
+}
+const readFile = node_fs_promises.readFile;
+const writeFile = node_fs_promises.writeFile;
+const readdir = node_fs_promises.readdir;
+const mkdir = node_fs_promises.mkdir;
+const stat = node_fs_promises.stat;
+const unlink = node_fs_promises.unlink;
+const rename = node_fs_promises.rename;
+const rm = node_fs_promises.rm;
+const cp = node_fs_promises.cp;
+
 //#endregion
 //#region src/utils/logger.ts
 const logsDir = node_path.join(node_os.tmpdir(), "scaffold-mcp-logs");
@@ -70,6 +179,29 @@ const log = {
 
 //#endregion
 //#region src/services/TemplatesManagerService.ts
+/**
+* TemplatesManagerService
+*
+* DESIGN PATTERNS:
+* - Class-based service pattern for encapsulating business logic
+* - Static methods for utility-like functionality
+* - File system traversal for workspace detection
+* - Configuration-driven template path resolution
+*
+* CODING STANDARDS:
+* - Service class names use PascalCase with 'Service' suffix
+* - Method names use camelCase with descriptive verbs
+* - Return types should be explicit (never use implicit any)
+* - Use async/await for asynchronous operations
+* - Handle errors with try-catch and throw descriptive Error objects
+* - Document public methods with JSDoc comments
+*
+* AVOID:
+* - Side effects in constructors (keep them lightweight)
+* - Mixing concerns (keep services focused on single domain)
+* - Direct coupling to other services (use dependency injection)
+* - Exposing internal implementation details
+*/
 var TemplatesManagerService = class TemplatesManagerService {
 	static SCAFFOLD_CONFIG_FILE = "scaffold.yaml";
 	static TEMPLATES_FOLDER = "templates";
@@ -92,18 +224,18 @@ var TemplatesManagerService = class TemplatesManagerService {
 	static async findTemplatesPath(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
 		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (await fs_extra.pathExists(toolkitConfigPath)) {
+		if (await pathExists(toolkitConfigPath)) {
 			const yaml = await import("js-yaml");
-			const content = await fs_extra.readFile(toolkitConfigPath, "utf-8");
+			const content = await node_fs_promises.readFile(toolkitConfigPath, "utf-8");
 			const config = yaml.load(content);
 			if (config?.templatesPath) {
 				const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.join(workspaceRoot, config.templatesPath);
-				if (await fs_extra.pathExists(templatesPath$1)) return templatesPath$1;
+				if (await pathExists(templatesPath$1)) return templatesPath$1;
 				else throw new Error(`Templates path specified in toolkit.yaml does not exist: ${templatesPath$1}`);
 			}
 		}
 		const templatesPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
-		if (await fs_extra.pathExists(templatesPath)) return templatesPath;
+		if (await pathExists(templatesPath)) return templatesPath;
 		throw new Error(`Templates folder not found at ${templatesPath}.\nEither create a 'templates' folder or specify templatesPath in toolkit.yaml`);
 	}
 	/**
@@ -113,8 +245,7 @@ var TemplatesManagerService = class TemplatesManagerService {
 		let currentPath = node_path.default.resolve(startPath);
 		const rootPath = node_path.default.parse(currentPath).root;
 		while (true) {
-			const gitPath = node_path.default.join(currentPath, ".git");
-			if (await fs_extra.pathExists(gitPath)) return currentPath;
+			if (await pathExists(node_path.default.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
 			currentPath = node_path.default.dirname(currentPath);
 		}
@@ -130,18 +261,18 @@ var TemplatesManagerService = class TemplatesManagerService {
 	static findTemplatesPathSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
 		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (fs_extra.pathExistsSync(toolkitConfigPath)) {
+		if (pathExistsSync(toolkitConfigPath)) {
 			const yaml = require("js-yaml");
-			const content = fs_extra.readFileSync(toolkitConfigPath, "utf-8");
+			const content = (0, node_fs.readFileSync)(toolkitConfigPath, "utf-8");
 			const config = yaml.load(content);
 			if (config?.templatesPath) {
 				const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.join(workspaceRoot, config.templatesPath);
-				if (fs_extra.pathExistsSync(templatesPath$1)) return templatesPath$1;
+				if (pathExistsSync(templatesPath$1)) return templatesPath$1;
 				else throw new Error(`Templates path specified in toolkit.yaml does not exist: ${templatesPath$1}`);
 			}
 		}
 		const templatesPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
-		if (fs_extra.pathExistsSync(templatesPath)) return templatesPath;
+		if (pathExistsSync(templatesPath)) return templatesPath;
 		throw new Error(`Templates folder not found at ${templatesPath}.\nEither create a 'templates' folder or specify templatesPath in toolkit.yaml`);
 	}
 	/**
@@ -151,8 +282,7 @@ var TemplatesManagerService = class TemplatesManagerService {
 		let currentPath = node_path.default.resolve(startPath);
 		const rootPath = node_path.default.parse(currentPath).root;
 		while (true) {
-			const gitPath = node_path.default.join(currentPath, ".git");
-			if (fs_extra.pathExistsSync(gitPath)) return currentPath;
+			if (pathExistsSync(node_path.default.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
 			currentPath = node_path.default.dirname(currentPath);
 		}
@@ -164,8 +294,8 @@ var TemplatesManagerService = class TemplatesManagerService {
 	* @returns true if templates folder exists and is a directory
 	*/
 	static async isInitialized(templatesPath) {
-		if (!await fs_extra.pathExists(templatesPath)) return false;
-		return (await fs_extra.stat(templatesPath)).isDirectory();
+		if (!await pathExists(templatesPath)) return false;
+		return (await node_fs_promises.stat(templatesPath)).isDirectory();
 	}
 	/**
 	* Get the scaffold config file name
@@ -188,9 +318,9 @@ var TemplatesManagerService = class TemplatesManagerService {
 	static async readToolkitConfig(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
 		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!await fs_extra.pathExists(toolkitConfigPath)) return null;
+		if (!await pathExists(toolkitConfigPath)) return null;
 		const yaml = await import("js-yaml");
-		const content = await fs_extra.readFile(toolkitConfigPath, "utf-8");
+		const content = await node_fs_promises.readFile(toolkitConfigPath, "utf-8");
 		return yaml.load(content);
 	}
 	/**
@@ -202,9 +332,9 @@ var TemplatesManagerService = class TemplatesManagerService {
 	static readToolkitConfigSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
 		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!fs_extra.pathExistsSync(toolkitConfigPath)) return null;
+		if (!pathExistsSync(toolkitConfigPath)) return null;
 		const yaml = require("js-yaml");
-		const content = fs_extra.readFileSync(toolkitConfigPath, "utf-8");
+		const content = (0, node_fs.readFileSync)(toolkitConfigPath, "utf-8");
 		return yaml.load(content);
 	}
 	/**
@@ -217,7 +347,7 @@ var TemplatesManagerService = class TemplatesManagerService {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
 		const toolkitConfigPath = node_path.default.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		const content = (await import("js-yaml")).dump(config, { indent: 2 });
-		await fs_extra.writeFile(toolkitConfigPath, content, "utf-8");
+		await node_fs_promises.writeFile(toolkitConfigPath, content, "utf-8");
 	}
 	/**
 	* Get the workspace root directory
@@ -244,6 +374,28 @@ var TemplatesManagerService = class TemplatesManagerService {
 /**
 * ProjectConfigResolver
 *
+* DESIGN PATTERNS:
+* - Class-based service pattern for resolving project configuration
+* - Priority-based configuration resolution (project.json > toolkit.yaml > package.json)
+* - Singleton-like static methods for common operations
+*
+* CODING STANDARDS:
+* - Service class names use PascalCase with 'Service' suffix
+* - Method names use camelCase with descriptive verbs
+* - Return types should be explicit (never use implicit any)
+* - Use async/await for asynchronous operations
+* - Handle errors with try-catch and throw descriptive Error objects
+* - Document public methods with JSDoc comments
+*
+* AVOID:
+* - Side effects in constructors (keep them lightweight)
+* - Mixing concerns (keep services focused on single domain)
+* - Direct coupling to other services (use dependency injection)
+* - Exposing internal implementation details
+*/
+/**
+* ProjectConfigResolver
+*
 * Resolves project configuration from multiple sources with priority:
 * 1. project.json (monorepo - Nx/Lerna/Turborepo)
 * 2. toolkit.yaml at workspace root (monolith)
@@ -271,8 +423,8 @@ var ProjectConfigResolver = class ProjectConfigResolver {
 				configSource: ConfigSource.TOOLKIT_YAML
 			};
 			const projectJsonPath = node_path.default.join(absolutePath, "project.json");
-			if (await fs_extra.pathExists(projectJsonPath)) {
-				const projectJson = await fs_extra.readJson(projectJsonPath);
+			if (await pathExists(projectJsonPath)) {
+				const projectJson = await readJson(projectJsonPath);
 				if (projectJson.sourceTemplate && typeof projectJson.sourceTemplate === "string" && projectJson.sourceTemplate.trim()) return {
 					type: ProjectType.MONOREPO,
 					sourceTemplate: projectJson.sourceTemplate.trim(),
@@ -364,7 +516,7 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 		const projectJsonPath = node_path.default.join(projectPath, "project.json");
 		try {
 			let projectJson;
-			if (await fs_extra.pathExists(projectJsonPath)) projectJson = await fs_extra.readJson(projectJsonPath);
+			if (await pathExists(projectJsonPath)) projectJson = await readJson(projectJsonPath);
 			else {
 				const relativePath = node_path.default.relative(projectPath, process.cwd());
 				projectJson = {
@@ -375,8 +527,7 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 				};
 			}
 			projectJson.sourceTemplate = sourceTemplate;
-			const content = JSON.stringify(projectJson, null, 2);
-			await fs_extra.writeFile(projectJsonPath, `${content}\n`);
+			await writeJson(projectJsonPath, projectJson);
 			log.info(`Created/updated project.json with sourceTemplate: ${sourceTemplate}`);
 		} catch (error) {
 			throw new Error(`Failed to create project.json: ${error instanceof Error ? error.message : String(error)}`);
@@ -386,6 +537,26 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 
 //#endregion
 //#region src/services/ProjectFinderService.ts
+/**
+* ProjectFinderService
+*
+* DESIGN PATTERNS:
+* - Class-based service pattern for encapsulating business logic
+* - Caching for performance optimization
+* - File system traversal for project detection
+*
+* CODING STANDARDS:
+* - Service class names use PascalCase with 'Service' suffix
+* - Method names use camelCase with descriptive verbs
+* - Return types should be explicit
+* - Use async/await for asynchronous operations
+* - Handle errors with try-catch and throw descriptive Error objects
+*
+* AVOID:
+* - Side effects in constructors
+* - Mixing concerns
+* - Direct coupling to other services
+*/
 var ProjectFinderService = class {
 	projectCache = /* @__PURE__ */ new Map();
 	workspaceRoot;
@@ -436,7 +607,7 @@ var ProjectFinderService = class {
 	async loadProjectConfig(projectJsonPath) {
 		if (this.projectCache.has(projectJsonPath)) return this.projectCache.get(projectJsonPath);
 		try {
-			const content = await fs_extra.readFile(projectJsonPath, "utf-8");
+			const content = await node_fs_promises.readFile(projectJsonPath, "utf-8");
 			const config = JSON.parse(content);
 			const projectConfig = {
 				name: config.name || node_path.default.basename(node_path.default.dirname(projectJsonPath)),
@@ -456,7 +627,7 @@ var ProjectFinderService = class {
 	loadProjectConfigSync(projectJsonPath) {
 		if (this.projectCache.has(projectJsonPath)) return this.projectCache.get(projectJsonPath);
 		try {
-			const content = fs_extra.readFileSync(projectJsonPath, "utf-8");
+			const content = (0, node_fs.readFileSync)(projectJsonPath, "utf-8");
 			const config = JSON.parse(content);
 			const projectConfig = {
 				name: config.name || node_path.default.basename(node_path.default.dirname(projectJsonPath)),
@@ -544,9 +715,9 @@ var ScaffoldProcessingService = class {
 			if (!item) continue;
 			const itemPath = node_path.default.join(dirPath, item);
 			try {
-				const stat = await this.fileSystem.stat(itemPath);
-				if (stat.isDirectory()) await this.trackCreatedFilesRecursive(itemPath, createdFiles);
-				else if (stat.isFile()) createdFiles.push(itemPath);
+				const stat$1 = await this.fileSystem.stat(itemPath);
+				if (stat$1.isDirectory()) await this.trackCreatedFilesRecursive(itemPath, createdFiles);
+				else if (stat$1.isFile()) createdFiles.push(itemPath);
 			} catch (error) {
 				console.warn(`Cannot stat ${itemPath}: ${error}`);
 			}
@@ -567,9 +738,9 @@ var ScaffoldProcessingService = class {
 			if (!item) continue;
 			const itemPath = node_path.default.join(dirPath, item);
 			try {
-				const stat = await this.fileSystem.stat(itemPath);
-				if (stat.isDirectory()) await this.trackExistingFilesRecursive(itemPath, existingFiles);
-				else if (stat.isFile()) existingFiles.push(itemPath);
+				const stat$1 = await this.fileSystem.stat(itemPath);
+				if (stat$1.isDirectory()) await this.trackExistingFilesRecursive(itemPath, existingFiles);
+				else if (stat$1.isFile()) existingFiles.push(itemPath);
 			} catch (error) {
 				console.warn(`Cannot stat ${itemPath}: ${error}`);
 			}
@@ -704,6 +875,27 @@ const sections = {
 //#endregion
 //#region src/utils/projectTypeDetector.ts
 /**
+* projectTypeDetector Utilities
+*
+* DESIGN PATTERNS:
+* - Pure function pattern: No side effects, deterministic output
+* - Single domain focus: All functions related to project type detection
+* - Composability: Functions can be combined to create complex behavior
+*
+* CODING STANDARDS:
+* - Function names use camelCase with descriptive verbs (validate, format, parse, transform)
+* - All functions should be pure (same input = same output, no side effects)
+* - Use explicit return types
+* - Document complex logic with JSDoc comments
+* - Keep functions small and focused on single responsibility
+*
+* AVOID:
+* - Side effects (mutations, I/O, random values, Date.now(), etc.)
+* - Stateful behavior or closures with mutable state
+* - Dependencies on external services or global variables
+* - Classes (use pure functions instead)
+*/
+/**
 * Monorepo configuration files that indicate a monorepo setup
 */
 const MONOREPO_INDICATOR_FILES = [
@@ -729,8 +921,8 @@ const MONOREPO_INDICATOR_FILES = [
 async function detectProjectType(workspaceRoot) {
 	const indicators = [];
 	const toolkitYamlPath = node_path.default.join(workspaceRoot, "toolkit.yaml");
-	if (await fs_extra.pathExists(toolkitYamlPath)) try {
-		const content = await fs_extra.readFile(toolkitYamlPath, "utf-8");
+	if (await pathExists(toolkitYamlPath)) try {
+		const content = await node_fs_promises.readFile(toolkitYamlPath, "utf-8");
 		const config = js_yaml.load(content);
 		if (config?.projectType) {
 			indicators.push(`toolkit.yaml specifies ${config.projectType}`);
@@ -740,19 +932,16 @@ async function detectProjectType(workspaceRoot) {
 			};
 		}
 	} catch {}
-	for (const filename of MONOREPO_INDICATOR_FILES) {
-		const filePath = node_path.default.join(workspaceRoot, filename);
-		if (await fs_extra.pathExists(filePath)) {
-			indicators.push(`${filename} found`);
-			return {
-				projectType: ProjectType.MONOREPO,
-				indicators
-			};
-		}
+	for (const filename of MONOREPO_INDICATOR_FILES) if (await pathExists(node_path.default.join(workspaceRoot, filename))) {
+		indicators.push(`${filename} found`);
+		return {
+			projectType: ProjectType.MONOREPO,
+			indicators
+		};
 	}
 	const packageJsonPath = node_path.default.join(workspaceRoot, "package.json");
-	if (await fs_extra.pathExists(packageJsonPath)) try {
-		if ((await fs_extra.readJson(packageJsonPath)).workspaces) {
+	if (await pathExists(packageJsonPath)) try {
+		if ((await readJson(packageJsonPath)).workspaces) {
 			indicators.push("package.json with workspaces found");
 			return {
 				projectType: ProjectType.MONOREPO,
@@ -794,12 +983,44 @@ exports.ProjectFinderService = ProjectFinderService;
 exports.ProjectType = ProjectType;
 exports.ScaffoldProcessingService = ScaffoldProcessingService;
 exports.TemplatesManagerService = TemplatesManagerService;
+exports.accessSync = node_fs.accessSync;
+exports.copy = copy;
+exports.cp = cp;
 exports.detectProjectType = detectProjectType;
+exports.ensureDir = ensureDir;
+exports.ensureDirSync = ensureDirSync;
+Object.defineProperty(exports, 'fs', {
+  enumerable: true,
+  get: function () {
+    return node_fs_promises;
+  }
+});
 exports.icons = icons;
 exports.isMonolith = isMonolith;
 exports.isMonorepo = isMonorepo;
 exports.log = log;
 exports.logger = logger;
 exports.messages = messages;
+exports.mkdir = mkdir;
+exports.mkdirSync = node_fs.mkdirSync;
+exports.move = move;
+exports.outputFile = outputFile;
+exports.pathExists = pathExists;
+exports.pathExistsSync = pathExistsSync;
 exports.print = print;
-exports.sections = sections;
+exports.readFile = readFile;
+exports.readFileSync = node_fs.readFileSync;
+exports.readJson = readJson;
+exports.readJsonSync = readJsonSync;
+exports.readdir = readdir;
+exports.remove = remove;
+exports.rename = rename;
+exports.rm = rm;
+exports.sections = sections;
+exports.stat = stat;
+exports.statSync = node_fs.statSync;
+exports.unlink = unlink;
+exports.writeFile = writeFile;
+exports.writeFileSync = node_fs.writeFileSync;
+exports.writeJson = writeJson;
+exports.writeJsonSync = writeJsonSync;

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import * as fs from "node:fs/promises";
+import { accessSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import pino from "pino";
 
 //#region src/constants/projectType.d.ts
@@ -43,6 +45,7 @@ interface NxProjectJson {
 }
 //#endregion
 //#region src/types/index.d.ts
+
 /**
  * Toolkit configuration from toolkit.yaml
  */
@@ -337,6 +340,69 @@ declare class TemplatesManagerService {
   static getWorkspaceRootSync(startPath?: string): string;
 }
 //#endregion
+//#region src/utils/fsHelpers.d.ts
+/**
+ * Check if a file or directory exists
+ */
+declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Check if a file or directory exists (sync)
+ */
+declare function pathExistsSync(filePath: string): boolean;
+/**
+ * Ensure a directory exists, creating it recursively if needed
+ */
+declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Ensure a directory exists (sync), creating it recursively if needed
+ */
+declare function ensureDirSync(dirPath: string): void;
+/**
+ * Remove a file or directory recursively
+ */
+declare function remove(filePath: string): Promise<void>;
+/**
+ * Copy a file or directory recursively
+ */
+declare function copy(src: string, dest: string): Promise<void>;
+/**
+ * Move a file or directory
+ */
+declare function move(src: string, dest: string): Promise<void>;
+/**
+ * Read and parse a JSON file
+ */
+declare function readJson<T = unknown>(filePath: string): Promise<T>;
+/**
+ * Read and parse a JSON file (sync)
+ */
+declare function readJsonSync<T = unknown>(filePath: string): T;
+/**
+ * Write an object as JSON to a file
+ */
+declare function writeJson(filePath: string, data: unknown, options?: {
+  spaces?: number;
+}): Promise<void>;
+/**
+ * Write an object as JSON to a file (sync)
+ */
+declare function writeJsonSync(filePath: string, data: unknown, options?: {
+  spaces?: number;
+}): void;
+/**
+ * Output file - writes content ensuring directory exists
+ */
+declare function outputFile(filePath: string, content: string): Promise<void>;
+declare const readFile: typeof fs.readFile;
+declare const writeFile: typeof fs.writeFile;
+declare const readdir: typeof fs.readdir;
+declare const mkdir: typeof fs.mkdir;
+declare const stat: typeof fs.stat;
+declare const unlink: typeof fs.unlink;
+declare const rename: typeof fs.rename;
+declare const rm: typeof fs.rm;
+declare const cp: typeof fs.cp;
+//#endregion
 //#region src/utils/logger.d.ts
 declare const logger: pino.Logger<never, boolean>;
 declare const log: {
@@ -514,4 +580,4 @@ declare function isMonorepo(workspaceRoot: string): Promise<boolean>;
  */
 declare function isMonolith(workspaceRoot: string): Promise<boolean>;
 //#endregion
-export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ProjectTypeDetectionResult, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, detectProjectType, icons, isMonolith, isMonorepo, log, logger, messages, print, sections };
+export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ProjectTypeDetectionResult, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, accessSync, copy, cp, detectProjectType, ensureDir, ensureDirSync, fs, icons, isMonolith, isMonorepo, log, logger, messages, mkdir, mkdirSync, move, outputFile, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, rename, rm, sections, stat, statSync, unlink, writeFile, writeFileSync, writeJson, writeJsonSync };

package/dist/{index.d.ts → index.d.mts}

@@ -1,3 +1,5 @@
+import * as fs from "node:fs/promises";
+import { accessSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import pino from "pino";
 
 //#region src/constants/projectType.d.ts
@@ -43,6 +45,7 @@ interface NxProjectJson {
 }
 //#endregion
 //#region src/types/index.d.ts
+
 /**
  * Toolkit configuration from toolkit.yaml
  */
@@ -337,6 +340,69 @@ declare class TemplatesManagerService {
   static getWorkspaceRootSync(startPath?: string): string;
 }
 //#endregion
+//#region src/utils/fsHelpers.d.ts
+/**
+ * Check if a file or directory exists
+ */
+declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Check if a file or directory exists (sync)
+ */
+declare function pathExistsSync(filePath: string): boolean;
+/**
+ * Ensure a directory exists, creating it recursively if needed
+ */
+declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Ensure a directory exists (sync), creating it recursively if needed
+ */
+declare function ensureDirSync(dirPath: string): void;
+/**
+ * Remove a file or directory recursively
+ */
+declare function remove(filePath: string): Promise<void>;
+/**
+ * Copy a file or directory recursively
+ */
+declare function copy(src: string, dest: string): Promise<void>;
+/**
+ * Move a file or directory
+ */
+declare function move(src: string, dest: string): Promise<void>;
+/**
+ * Read and parse a JSON file
+ */
+declare function readJson<T = unknown>(filePath: string): Promise<T>;
+/**
+ * Read and parse a JSON file (sync)
+ */
+declare function readJsonSync<T = unknown>(filePath: string): T;
+/**
+ * Write an object as JSON to a file
+ */
+declare function writeJson(filePath: string, data: unknown, options?: {
+  spaces?: number;
+}): Promise<void>;
+/**
+ * Write an object as JSON to a file (sync)
+ */
+declare function writeJsonSync(filePath: string, data: unknown, options?: {
+  spaces?: number;
+}): void;
+/**
+ * Output file - writes content ensuring directory exists
+ */
+declare function outputFile(filePath: string, content: string): Promise<void>;
+declare const readFile: typeof fs.readFile;
+declare const writeFile: typeof fs.writeFile;
+declare const readdir: typeof fs.readdir;
+declare const mkdir: typeof fs.mkdir;
+declare const stat: typeof fs.stat;
+declare const unlink: typeof fs.unlink;
+declare const rename: typeof fs.rename;
+declare const rm: typeof fs.rm;
+declare const cp: typeof fs.cp;
+//#endregion
 //#region src/utils/logger.d.ts
 declare const logger: pino.Logger<never, boolean>;
 declare const log: {
@@ -514,4 +580,4 @@ declare function isMonorepo(workspaceRoot: string): Promise<boolean>;
  */
 declare function isMonolith(workspaceRoot: string): Promise<boolean>;
 //#endregion
-export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ProjectTypeDetectionResult, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, detectProjectType, icons, isMonolith, isMonorepo, log, logger, messages, print, sections };
+export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ProjectTypeDetectionResult, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, accessSync, copy, cp, detectProjectType, ensureDir, ensureDirSync, fs, icons, isMonolith, isMonorepo, log, logger, messages, mkdir, mkdirSync, move, outputFile, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, rename, rm, sections, stat, statSync, unlink, writeFile, writeFileSync, writeJson, writeJsonSync };

package/dist/{index.js → index.mjs}

@@ -1,7 +1,8 @@
 import { createRequire } from "node:module";
-import * as path$1 from "node:path";
-import path from "node:path";
-import * as fs from "fs-extra";
+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";
 import pino from "pino";
 import * as yaml from "js-yaml";
@@ -27,14 +28,122 @@ const ConfigSource = {
 	TOOLKIT_YAML: "toolkit.yaml"
 };
 
+//#endregion
+//#region src/utils/fsHelpers.ts
+/**
+* Native FS Helper Functions
+*
+* Provides fs-extra-like API using native node:fs/promises
+* to avoid ESM compatibility issues with fs-extra
+*/
+/**
+* Check if a file or directory exists
+*/
+async function pathExists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if a file or directory exists (sync)
+*/
+function pathExistsSync(filePath) {
+	try {
+		accessSync(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Ensure a directory exists, creating it recursively if needed
+*/
+async function ensureDir(dirPath) {
+	await fs.mkdir(dirPath, { recursive: true });
+}
+/**
+* Ensure a directory exists (sync), creating it recursively if needed
+*/
+function ensureDirSync(dirPath) {
+	mkdirSync(dirPath, { recursive: true });
+}
+/**
+* Remove a file or directory recursively
+*/
+async function remove(filePath) {
+	await fs.rm(filePath, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Copy a file or directory recursively
+*/
+async function copy(src, dest) {
+	await fs.cp(src, dest, { recursive: true });
+}
+/**
+* Move a file or directory
+*/
+async function move(src, dest) {
+	await ensureDir(nodePath.dirname(dest));
+	await fs.rename(src, dest);
+}
+/**
+* Read and parse a JSON file
+*/
+async function readJson(filePath) {
+	const content = await fs.readFile(filePath, "utf-8");
+	return JSON.parse(content);
+}
+/**
+* Read and parse a JSON file (sync)
+*/
+function readJsonSync(filePath) {
+	const content = readFileSync(filePath, "utf-8");
+	return JSON.parse(content);
+}
+/**
+* Write an object as JSON to a file
+*/
+async function writeJson(filePath, data, options) {
+	const content = JSON.stringify(data, null, options?.spaces ?? 2);
+	await fs.writeFile(filePath, `${content}\n`, "utf-8");
+}
+/**
+* Write an object as JSON to a file (sync)
+*/
+function writeJsonSync(filePath, data, options) {
+	writeFileSync(filePath, `${JSON.stringify(data, null, options?.spaces ?? 2)}\n`, "utf-8");
+}
+/**
+* Output file - writes content ensuring directory exists
+*/
+async function outputFile(filePath, content) {
+	await ensureDir(nodePath.dirname(filePath));
+	await fs.writeFile(filePath, content, "utf-8");
+}
+const readFile = fs.readFile;
+const writeFile = fs.writeFile;
+const readdir = fs.readdir;
+const mkdir = fs.mkdir;
+const stat = fs.stat;
+const unlink = fs.unlink;
+const rename = fs.rename;
+const rm = fs.rm;
+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
 }));
@@ -47,6 +156,29 @@ const log = {
 
 //#endregion
 //#region src/services/TemplatesManagerService.ts
+/**
+* TemplatesManagerService
+*
+* DESIGN PATTERNS:
+* - Class-based service pattern for encapsulating business logic
+* - Static methods for utility-like functionality
+* - File system traversal for workspace detection
+* - Configuration-driven template path resolution
+*
+* CODING STANDARDS:
+* - Service class names use PascalCase with 'Service' suffix
+* - Method names use camelCase with descriptive verbs
+* - Return types should be explicit (never use implicit any)
+* - Use async/await for asynchronous operations
+* - Handle errors with try-catch and throw descriptive Error objects
+* - Document public methods with JSDoc comments
+*
+* AVOID:
+* - Side effects in constructors (keep them lightweight)
+* - Mixing concerns (keep services focused on single domain)
+* - Direct coupling to other services (use dependency injection)
+* - Exposing internal implementation details
+*/
 var TemplatesManagerService = class TemplatesManagerService {
 	static SCAFFOLD_CONFIG_FILE = "scaffold.yaml";
 	static TEMPLATES_FOLDER = "templates";
@@ -68,32 +200,31 @@ 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 fs.pathExists(toolkitConfigPath)) {
+		const toolkitConfigPath = nodePath.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 fs.pathExists(templatesPath$1)) return templatesPath$1;
+				const templatesPath$1 = nodePath.isAbsolute(config.templatesPath) ? config.templatesPath : nodePath.join(workspaceRoot, config.templatesPath);
+				if (await pathExists(templatesPath$1)) return templatesPath$1;
 				else throw new Error(`Templates path specified in toolkit.yaml does not exist: ${templatesPath$1}`);
 			}
 		}
-		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
-		if (await fs.pathExists(templatesPath)) return templatesPath;
+		const templatesPath = nodePath.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
+		if (await pathExists(templatesPath)) return templatesPath;
 		throw new Error(`Templates folder not found at ${templatesPath}.\nEither create a 'templates' folder or specify templatesPath in toolkit.yaml`);
 	}
 	/**
 	* 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) {
-			const gitPath = path.join(currentPath, ".git");
-			if (await fs.pathExists(gitPath)) 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);
 		}
 	}
 	/**
@@ -106,32 +237,31 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static findTemplatesPathSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (fs.pathExistsSync(toolkitConfigPath)) {
+		const toolkitConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (pathExistsSync(toolkitConfigPath)) {
 			const yaml$1 = __require("js-yaml");
-			const content = fs.readFileSync(toolkitConfigPath, "utf-8");
+			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 (fs.pathExistsSync(templatesPath$1)) return templatesPath$1;
+				const templatesPath$1 = nodePath.isAbsolute(config.templatesPath) ? config.templatesPath : nodePath.join(workspaceRoot, config.templatesPath);
+				if (pathExistsSync(templatesPath$1)) return templatesPath$1;
 				else throw new Error(`Templates path specified in toolkit.yaml does not exist: ${templatesPath$1}`);
 			}
 		}
-		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
-		if (fs.pathExistsSync(templatesPath)) return templatesPath;
+		const templatesPath = nodePath.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
+		if (pathExistsSync(templatesPath)) return templatesPath;
 		throw new Error(`Templates folder not found at ${templatesPath}.\nEither create a 'templates' folder or specify templatesPath in toolkit.yaml`);
 	}
 	/**
 	* 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) {
-			const gitPath = path.join(currentPath, ".git");
-			if (fs.pathExistsSync(gitPath)) return currentPath;
+			if (pathExistsSync(nodePath.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
-			currentPath = path.dirname(currentPath);
+			currentPath = nodePath.dirname(currentPath);
 		}
 	}
 	/**
@@ -141,7 +271,7 @@ var TemplatesManagerService = class TemplatesManagerService {
 	* @returns true if templates folder exists and is a directory
 	*/
 	static async isInitialized(templatesPath) {
-		if (!await fs.pathExists(templatesPath)) return false;
+		if (!await pathExists(templatesPath)) return false;
 		return (await fs.stat(templatesPath)).isDirectory();
 	}
 	/**
@@ -164,8 +294,8 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static async readToolkitConfig(startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!await fs.pathExists(toolkitConfigPath)) return null;
+		const toolkitConfigPath = nodePath.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");
 		return yaml$1.load(content);
@@ -178,10 +308,10 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static readToolkitConfigSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
-		if (!fs.pathExistsSync(toolkitConfigPath)) return null;
+		const toolkitConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (!pathExistsSync(toolkitConfigPath)) return null;
 		const yaml$1 = __require("js-yaml");
-		const content = fs.readFileSync(toolkitConfigPath, "utf-8");
+		const content = readFileSync$1(toolkitConfigPath, "utf-8");
 		return yaml$1.load(content);
 	}
 	/**
@@ -192,7 +322,7 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static async writeToolkitConfig(config, startPath = process.cwd()) {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		const toolkitConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		const content = (await import("js-yaml")).dump(config, { indent: 2 });
 		await fs.writeFile(toolkitConfigPath, content, "utf-8");
 	}
@@ -221,6 +351,28 @@ var TemplatesManagerService = class TemplatesManagerService {
 /**
 * ProjectConfigResolver
 *
+* DESIGN PATTERNS:
+* - Class-based service pattern for resolving project configuration
+* - Priority-based configuration resolution (project.json > toolkit.yaml > package.json)
+* - Singleton-like static methods for common operations
+*
+* CODING STANDARDS:
+* - Service class names use PascalCase with 'Service' suffix
+* - Method names use camelCase with descriptive verbs
+* - Return types should be explicit (never use implicit any)
+* - Use async/await for asynchronous operations
+* - Handle errors with try-catch and throw descriptive Error objects
+* - Document public methods with JSDoc comments
+*
+* AVOID:
+* - Side effects in constructors (keep them lightweight)
+* - Mixing concerns (keep services focused on single domain)
+* - Direct coupling to other services (use dependency injection)
+* - Exposing internal implementation details
+*/
+/**
+* ProjectConfigResolver
+*
 * Resolves project configuration from multiple sources with priority:
 * 1. project.json (monorepo - Nx/Lerna/Turborepo)
 * 2. toolkit.yaml at workspace root (monolith)
@@ -241,15 +393,15 @@ 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");
-			if (await fs.pathExists(projectJsonPath)) {
-				const projectJson = await fs.readJson(projectJsonPath);
+			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 {
 					type: ProjectType.MONOREPO,
 					sourceTemplate: projectJson.sourceTemplate.trim(),
@@ -338,12 +490,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 fs.pathExists(projectJsonPath)) projectJson = await fs.readJson(projectJsonPath);
+			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",
@@ -352,8 +504,7 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 				};
 			}
 			projectJson.sourceTemplate = sourceTemplate;
-			const content = JSON.stringify(projectJson, null, 2);
-			await fs.writeFile(projectJsonPath, `${content}\n`);
+			await writeJson(projectJsonPath, projectJson);
 			log.info(`Created/updated project.json with sourceTemplate: ${sourceTemplate}`);
 		} catch (error) {
 			throw new Error(`Failed to create project.json: ${error instanceof Error ? error.message : String(error)}`);
@@ -363,6 +514,26 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 
 //#endregion
 //#region src/services/ProjectFinderService.ts
+/**
+* ProjectFinderService
+*
+* DESIGN PATTERNS:
+* - Class-based service pattern for encapsulating business logic
+* - Caching for performance optimization
+* - File system traversal for project detection
+*
+* CODING STANDARDS:
+* - Service class names use PascalCase with 'Service' suffix
+* - Method names use camelCase with descriptive verbs
+* - Return types should be explicit
+* - Use async/await for asynchronous operations
+* - Handle errors with try-catch and throw descriptive Error objects
+*
+* AVOID:
+* - Side effects in constructors
+* - Mixing concerns
+* - Direct coupling to other services
+*/
 var ProjectFinderService = class {
 	projectCache = /* @__PURE__ */ new Map();
 	workspaceRoot;
@@ -376,15 +547,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;
 	}
@@ -395,15 +566,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;
 	}
@@ -416,8 +587,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
 			};
@@ -433,11 +604,11 @@ var ProjectFinderService = class {
 	loadProjectConfigSync(projectJsonPath) {
 		if (this.projectCache.has(projectJsonPath)) return this.projectCache.get(projectJsonPath);
 		try {
-			const content = fs.readFileSync(projectJsonPath, "utf-8");
+			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
 			};
@@ -497,7 +668,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;
@@ -519,11 +690,11 @@ 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 = await this.fileSystem.stat(itemPath);
-				if (stat.isDirectory()) await this.trackCreatedFilesRecursive(itemPath, createdFiles);
-				else if (stat.isFile()) createdFiles.push(itemPath);
+				const stat$1 = await this.fileSystem.stat(itemPath);
+				if (stat$1.isDirectory()) await this.trackCreatedFilesRecursive(itemPath, createdFiles);
+				else if (stat$1.isFile()) createdFiles.push(itemPath);
 			} catch (error) {
 				console.warn(`Cannot stat ${itemPath}: ${error}`);
 			}
@@ -542,11 +713,11 @@ 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 = await this.fileSystem.stat(itemPath);
-				if (stat.isDirectory()) await this.trackExistingFilesRecursive(itemPath, existingFiles);
-				else if (stat.isFile()) existingFiles.push(itemPath);
+				const stat$1 = await this.fileSystem.stat(itemPath);
+				if (stat$1.isDirectory()) await this.trackExistingFilesRecursive(itemPath, existingFiles);
+				else if (stat$1.isFile()) existingFiles.push(itemPath);
 			} catch (error) {
 				console.warn(`Cannot stat ${itemPath}: ${error}`);
 			}
@@ -681,6 +852,27 @@ const sections = {
 //#endregion
 //#region src/utils/projectTypeDetector.ts
 /**
+* projectTypeDetector Utilities
+*
+* DESIGN PATTERNS:
+* - Pure function pattern: No side effects, deterministic output
+* - Single domain focus: All functions related to project type detection
+* - Composability: Functions can be combined to create complex behavior
+*
+* CODING STANDARDS:
+* - Function names use camelCase with descriptive verbs (validate, format, parse, transform)
+* - All functions should be pure (same input = same output, no side effects)
+* - Use explicit return types
+* - Document complex logic with JSDoc comments
+* - Keep functions small and focused on single responsibility
+*
+* AVOID:
+* - Side effects (mutations, I/O, random values, Date.now(), etc.)
+* - Stateful behavior or closures with mutable state
+* - Dependencies on external services or global variables
+* - Classes (use pure functions instead)
+*/
+/**
 * Monorepo configuration files that indicate a monorepo setup
 */
 const MONOREPO_INDICATOR_FILES = [
@@ -705,8 +897,8 @@ const MONOREPO_INDICATOR_FILES = [
 */
 async function detectProjectType(workspaceRoot) {
 	const indicators = [];
-	const toolkitYamlPath = path.join(workspaceRoot, "toolkit.yaml");
-	if (await fs.pathExists(toolkitYamlPath)) try {
+	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);
 		if (config?.projectType) {
@@ -717,19 +909,16 @@ async function detectProjectType(workspaceRoot) {
 			};
 		}
 	} catch {}
-	for (const filename of MONOREPO_INDICATOR_FILES) {
-		const filePath = path.join(workspaceRoot, filename);
-		if (await fs.pathExists(filePath)) {
-			indicators.push(`${filename} found`);
-			return {
-				projectType: ProjectType.MONOREPO,
-				indicators
-			};
-		}
-	}
-	const packageJsonPath = path.join(workspaceRoot, "package.json");
-	if (await fs.pathExists(packageJsonPath)) try {
-		if ((await fs.readJson(packageJsonPath)).workspaces) {
+	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 = nodePath.join(workspaceRoot, "package.json");
+	if (await pathExists(packageJsonPath)) try {
+		if ((await readJson(packageJsonPath)).workspaces) {
 			indicators.push("package.json with workspaces found");
 			return {
 				projectType: ProjectType.MONOREPO,
@@ -765,4 +954,4 @@ async function isMonolith(workspaceRoot) {
 }
 
 //#endregion
-export { ConfigSource, ProjectConfigResolver, ProjectFinderService, ProjectType, ScaffoldProcessingService, TemplatesManagerService, detectProjectType, icons, isMonolith, isMonorepo, log, logger, messages, print, sections };
+export { ConfigSource, ProjectConfigResolver, ProjectFinderService, ProjectType, ScaffoldProcessingService, TemplatesManagerService, accessSync, copy, cp, detectProjectType, ensureDir, ensureDirSync, fs, icons, isMonolith, isMonorepo, log, logger, messages, mkdir, mkdirSync, move, outputFile, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, rename, rm, sections, stat, statSync, unlink, writeFile, writeFileSync, writeJson, writeJsonSync };

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.2",
+  "version": "1.0.4",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {
@@ -23,7 +23,7 @@
     "code-generation"
   ],
   "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "files": [
     "dist",
@@ -31,18 +31,16 @@
   ],
   "dependencies": {
     "chalk": "5.6.2",
-    "fs-extra": "11.3.2",
     "js-yaml": "4.1.0",
     "ora": "^9.0.0",
     "pino": "^10.0.0"
   },
   "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/ora": "^3.2.0",
     "@vitest/coverage-v8": "^3.0.0",
-    "tsdown": "^0.15.6",
+    "tsdown": "^0.16.4",
     "typescript": "5.9.3",
     "vitest": "^3.0.0"
   },
@@ -52,7 +50,7 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
+      "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
     "./package.json": "./package.json"