@agiflowai/aicode-utils 0.4.0

package/dist/index.cjs

@@ -0,0 +1,337 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+let fs_extra = require("fs-extra");
+fs_extra = __toESM(fs_extra);
+
+//#region src/services/ProjectFinderService.ts
+var ProjectFinderService = class {
+	projectCache = /* @__PURE__ */ new Map();
+	workspaceRoot;
+	constructor(workspaceRoot) {
+		this.workspaceRoot = workspaceRoot || process.cwd();
+	}
+	/**
+	* Find the project containing a given file by walking up the directory tree
+	*
+	* @param filePath - Absolute path to the file
+	* @returns Project configuration or null if not found
+	*/
+	async findProjectForFile(filePath) {
+		const normalizedPath = node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(this.workspaceRoot, filePath);
+		let currentDir = node_path.default.dirname(normalizedPath);
+		while (currentDir !== "/" && currentDir.startsWith(this.workspaceRoot)) {
+			const projectJsonPath = node_path.default.join(currentDir, "project.json");
+			try {
+				const project = await this.loadProjectConfig(projectJsonPath);
+				if (project) return project;
+			} catch {}
+			currentDir = node_path.default.dirname(currentDir);
+		}
+		return null;
+	}
+	/**
+	* Find the project containing a given file (synchronous version)
+	*
+	* @param filePath - Absolute path to the file
+	* @returns Project configuration or null if not found
+	*/
+	findProjectForFileSync(filePath) {
+		const normalizedPath = node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(this.workspaceRoot, filePath);
+		let currentDir = node_path.default.dirname(normalizedPath);
+		while (currentDir !== "/" && currentDir.startsWith(this.workspaceRoot)) {
+			const projectJsonPath = node_path.default.join(currentDir, "project.json");
+			try {
+				const project = this.loadProjectConfigSync(projectJsonPath);
+				if (project) return project;
+			} catch {}
+			currentDir = node_path.default.dirname(currentDir);
+		}
+		return null;
+	}
+	/**
+	* Load and parse a project.json file
+	*/
+	async loadProjectConfig(projectJsonPath) {
+		if (this.projectCache.has(projectJsonPath)) return this.projectCache.get(projectJsonPath);
+		try {
+			const content = await fs_extra.readFile(projectJsonPath, "utf-8");
+			const config = JSON.parse(content);
+			const projectConfig = {
+				name: config.name || node_path.default.basename(node_path.default.dirname(projectJsonPath)),
+				root: node_path.default.dirname(projectJsonPath),
+				sourceTemplate: config.sourceTemplate,
+				projectType: config.projectType
+			};
+			this.projectCache.set(projectJsonPath, projectConfig);
+			return projectConfig;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Load and parse a project.json file (synchronous version)
+	*/
+	loadProjectConfigSync(projectJsonPath) {
+		if (this.projectCache.has(projectJsonPath)) return this.projectCache.get(projectJsonPath);
+		try {
+			const content = fs_extra.readFileSync(projectJsonPath, "utf-8");
+			const config = JSON.parse(content);
+			const projectConfig = {
+				name: config.name || node_path.default.basename(node_path.default.dirname(projectJsonPath)),
+				root: node_path.default.dirname(projectJsonPath),
+				sourceTemplate: config.sourceTemplate,
+				projectType: config.projectType
+			};
+			this.projectCache.set(projectJsonPath, projectConfig);
+			return projectConfig;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Get the workspace root
+	*/
+	getWorkspaceRoot() {
+		return this.workspaceRoot;
+	}
+	/**
+	* Clear the project cache
+	*/
+	clearCache() {
+		this.projectCache.clear();
+	}
+};
+
+//#endregion
+//#region src/services/ScaffoldProcessingService.ts
+/**
+* Shared service for common scaffolding operations like processing templates and tracking files
+*/
+var ScaffoldProcessingService = class {
+	constructor(fileSystem, variableReplacer) {
+		this.fileSystem = fileSystem;
+		this.variableReplacer = variableReplacer;
+	}
+	/**
+	* Process a target path for variable replacement, handling both files and directories
+	*/
+	async processTargetForVariableReplacement(targetPath, variables) {
+		if ((await this.fileSystem.stat(targetPath)).isDirectory()) await this.variableReplacer.processFilesForVariableReplacement(targetPath, variables);
+		else await this.variableReplacer.replaceVariablesInFile(targetPath, variables);
+	}
+	/**
+	* Track all created files, handling both single files and directories
+	*/
+	async trackCreatedFiles(targetPath, createdFiles) {
+		if ((await this.fileSystem.stat(targetPath)).isDirectory()) await this.trackCreatedFilesRecursive(targetPath, createdFiles);
+		else createdFiles.push(targetPath);
+	}
+	/**
+	* Track all existing files, handling both single files and directories
+	*/
+	async trackExistingFiles(targetPath, existingFiles) {
+		if ((await this.fileSystem.stat(targetPath)).isDirectory()) await this.trackExistingFilesRecursive(targetPath, existingFiles);
+		else existingFiles.push(targetPath);
+	}
+	/**
+	* Copy source to target, then process templates and track files
+	* Now supports tracking existing files separately from created files
+	*/
+	async copyAndProcess(sourcePath, targetPath, variables, createdFiles, existingFiles) {
+		await this.fileSystem.ensureDir(node_path.default.dirname(targetPath));
+		if (await this.fileSystem.pathExists(targetPath) && existingFiles) {
+			await this.trackExistingFiles(targetPath, existingFiles);
+			return;
+		}
+		await this.fileSystem.copy(sourcePath, targetPath);
+		await this.processTargetForVariableReplacement(targetPath, variables);
+		await this.trackCreatedFiles(targetPath, createdFiles);
+	}
+	/**
+	* Recursively collect all file paths in a directory for created files
+	*/
+	async trackCreatedFilesRecursive(dirPath, createdFiles) {
+		let items = [];
+		try {
+			items = await this.fileSystem.readdir(dirPath);
+		} catch (error) {
+			console.warn(`Cannot read directory ${dirPath}: ${error}`);
+			return;
+		}
+		for (const item of items) {
+			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);
+			} catch (error) {
+				console.warn(`Cannot stat ${itemPath}: ${error}`);
+			}
+		}
+	}
+	/**
+	* Recursively collect all file paths in a directory for existing files
+	*/
+	async trackExistingFilesRecursive(dirPath, existingFiles) {
+		let items = [];
+		try {
+			items = await this.fileSystem.readdir(dirPath);
+		} catch (error) {
+			console.warn(`Cannot read directory ${dirPath}: ${error}`);
+			return;
+		}
+		for (const item of items) {
+			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);
+			} catch (error) {
+				console.warn(`Cannot stat ${itemPath}: ${error}`);
+			}
+		}
+	}
+};
+
+//#endregion
+//#region src/services/TemplatesManagerService.ts
+var TemplatesManagerService = class TemplatesManagerService {
+	static SCAFFOLD_CONFIG_FILE = "scaffold.yaml";
+	static TEMPLATES_FOLDER = "templates";
+	static TOOLKIT_CONFIG_FILE = "toolkit.yaml";
+	/**
+	* 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
+	* 4. Verify the templates directory exists
+	*
+	* @param startPath - The path to start searching from (defaults to process.cwd())
+	* @returns The absolute path to the templates directory
+	* @throws Error if templates directory is not found
+	*/
+	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)) {
+			const yaml = await import("js-yaml");
+			const content = await fs_extra.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;
+				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;
+		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 = 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 (currentPath === rootPath) return process.cwd();
+			currentPath = node_path.default.dirname(currentPath);
+		}
+	}
+	/**
+	* Get the templates path synchronously.
+	* Use this when you need immediate access and are sure templates exist.
+	*
+	* @param startPath - The path to start searching from (defaults to process.cwd())
+	* @returns The absolute path to the templates directory
+	* @throws Error if templates directory is not found
+	*/
+	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)) {
+			const yaml = require("js-yaml");
+			const content = fs_extra.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;
+				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;
+		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 = 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 (currentPath === rootPath) return process.cwd();
+			currentPath = node_path.default.dirname(currentPath);
+		}
+	}
+	/**
+	* Check if templates are initialized at the given path
+	*
+	* @param templatesPath - Path to check for templates
+	* @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();
+	}
+	/**
+	* Get the scaffold config file name
+	*/
+	static getConfigFileName() {
+		return TemplatesManagerService.SCAFFOLD_CONFIG_FILE;
+	}
+	/**
+	* Get the templates folder name
+	*/
+	static getTemplatesFolderName() {
+		return TemplatesManagerService.TEMPLATES_FOLDER;
+	}
+};
+
+//#endregion
+exports.ProjectFinderService = ProjectFinderService;
+exports.ScaffoldProcessingService = ScaffoldProcessingService;
+exports.TemplatesManagerService = TemplatesManagerService;

package/dist/index.d.cts

@@ -0,0 +1,242 @@
+//#region src/types/index.d.ts
+/**
+ * @agiflowai/aicode-utils - Type Definitions
+ *
+ * DESIGN PATTERNS:
+ * - Interface segregation: Keep interfaces focused and minimal
+ * - Type composition: Build complex types from simple primitives
+ * - Generics: Use type parameters for reusable, type-safe abstractions
+ *
+ * CODING STANDARDS:
+ * - Use PascalCase for type/interface names
+ * - Prefix interfaces with 'I' only for abstract contracts
+ * - Document complex types with JSDoc comments
+ * - Export all public types
+ *
+ * AVOID:
+ * - Any type unless absolutely necessary
+ * - Overly complex type gymnastics
+ * - Coupling types to implementation details
+ */
+/**
+ * Project configuration from project.json
+ */
+interface ProjectConfig {
+  name: string;
+  root: string;
+  sourceTemplate?: string;
+  projectType?: string;
+}
+/**
+ * Scaffold template include configuration
+ */
+interface ParsedInclude {
+  sourcePath: string;
+  targetPath: string;
+  conditions?: Record<string, string>;
+}
+/**
+ * Result of a scaffold operation
+ */
+interface ScaffoldResult {
+  success: boolean;
+  message: string;
+  warnings?: string[];
+  createdFiles?: string[];
+  existingFiles?: string[];
+}
+/**
+ * Abstract interface for file system operations
+ */
+interface IFileSystemService {
+  pathExists(path: string): Promise<boolean>;
+  readFile(path: string, encoding?: BufferEncoding): Promise<string>;
+  readJson(path: string): Promise<any>;
+  writeFile(path: string, content: string, encoding?: BufferEncoding): Promise<void>;
+  ensureDir(path: string): Promise<void>;
+  copy(src: string, dest: string): Promise<void>;
+  readdir(path: string): Promise<string[]>;
+  stat(path: string): Promise<{
+    isDirectory(): boolean;
+    isFile(): boolean;
+  }>;
+}
+/**
+ * Abstract interface for variable replacement in templates
+ */
+interface IVariableReplacementService {
+  processFilesForVariableReplacement(dirPath: string, variables: Record<string, any>): Promise<void>;
+  replaceVariablesInFile(filePath: string, variables: Record<string, any>): Promise<void>;
+  isBinaryFile(filePath: string): boolean;
+}
+/**
+ * Context object passed to generator functions
+ */
+interface GeneratorContext {
+  variables: Record<string, any>;
+  config: any;
+  targetPath: string;
+  templatePath: string;
+  fileSystem: IFileSystemService;
+  scaffoldConfigLoader: any;
+  variableReplacer: IVariableReplacementService;
+  ScaffoldProcessingService: any;
+  getRootPath: () => string;
+  getProjectPath: (projectPath: string) => string;
+}
+/**
+ * Type definition for generator functions
+ */
+type GeneratorFunction = (context: GeneratorContext) => Promise<ScaffoldResult>;
+//#endregion
+//#region src/services/ProjectFinderService.d.ts
+declare class ProjectFinderService {
+  private projectCache;
+  private workspaceRoot;
+  constructor(workspaceRoot?: string);
+  /**
+   * Find the project containing a given file by walking up the directory tree
+   *
+   * @param filePath - Absolute path to the file
+   * @returns Project configuration or null if not found
+   */
+  findProjectForFile(filePath: string): Promise<ProjectConfig | null>;
+  /**
+   * Find the project containing a given file (synchronous version)
+   *
+   * @param filePath - Absolute path to the file
+   * @returns Project configuration or null if not found
+   */
+  findProjectForFileSync(filePath: string): ProjectConfig | null;
+  /**
+   * Load and parse a project.json file
+   */
+  private loadProjectConfig;
+  /**
+   * Load and parse a project.json file (synchronous version)
+   */
+  private loadProjectConfigSync;
+  /**
+   * Get the workspace root
+   */
+  getWorkspaceRoot(): string;
+  /**
+   * Clear the project cache
+   */
+  clearCache(): void;
+}
+//#endregion
+//#region src/services/ScaffoldProcessingService.d.ts
+/**
+ * Shared service for common scaffolding operations like processing templates and tracking files
+ */
+declare class ScaffoldProcessingService {
+  private fileSystem;
+  private variableReplacer;
+  constructor(fileSystem: IFileSystemService, variableReplacer: IVariableReplacementService);
+  /**
+   * Process a target path for variable replacement, handling both files and directories
+   */
+  processTargetForVariableReplacement(targetPath: string, variables: Record<string, any>): Promise<void>;
+  /**
+   * Track all created files, handling both single files and directories
+   */
+  trackCreatedFiles(targetPath: string, createdFiles: string[]): Promise<void>;
+  /**
+   * Track all existing files, handling both single files and directories
+   */
+  trackExistingFiles(targetPath: string, existingFiles: string[]): Promise<void>;
+  /**
+   * Copy source to target, then process templates and track files
+   * Now supports tracking existing files separately from created files
+   */
+  copyAndProcess(sourcePath: string, targetPath: string, variables: Record<string, any>, createdFiles: string[], existingFiles?: string[]): Promise<void>;
+  /**
+   * Recursively collect all file paths in a directory for created files
+   */
+  private trackCreatedFilesRecursive;
+  /**
+   * Recursively collect all file paths in a directory for existing files
+   */
+  private trackExistingFilesRecursive;
+}
+//#endregion
+//#region src/services/TemplatesManagerService.d.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
+ */
+declare class TemplatesManagerService {
+  private static SCAFFOLD_CONFIG_FILE;
+  private static TEMPLATES_FOLDER;
+  private static TOOLKIT_CONFIG_FILE;
+  /**
+   * 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
+   * 4. Verify the templates directory exists
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The absolute path to the templates directory
+   * @throws Error if templates directory is not found
+   */
+  static findTemplatesPath(startPath?: string): Promise<string>;
+  /**
+   * Find the workspace root by searching upwards for .git folder
+   */
+  private static findWorkspaceRoot;
+  /**
+   * Get the templates path synchronously.
+   * Use this when you need immediate access and are sure templates exist.
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The absolute path to the templates directory
+   * @throws Error if templates directory is not found
+   */
+  static findTemplatesPathSync(startPath?: string): string;
+  /**
+   * Find the workspace root synchronously by searching upwards for .git folder
+   */
+  private static findWorkspaceRootSync;
+  /**
+   * Check if templates are initialized at the given path
+   *
+   * @param templatesPath - Path to check for templates
+   * @returns true if templates folder exists and is a directory
+   */
+  static isInitialized(templatesPath: string): Promise<boolean>;
+  /**
+   * Get the scaffold config file name
+   */
+  static getConfigFileName(): string;
+  /**
+   * Get the templates folder name
+   */
+  static getTemplatesFolderName(): string;
+}
+//#endregion
+export { GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, ParsedInclude, ProjectConfig, ProjectFinderService, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService };