@agiflowai/aicode-utils 0.4.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,315 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import * as fs from "fs-extra";
+
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+//#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 = path.isAbsolute(filePath) ? filePath : path.join(this.workspaceRoot, filePath);
+		let currentDir = path.dirname(normalizedPath);
+		while (currentDir !== "/" && currentDir.startsWith(this.workspaceRoot)) {
+			const projectJsonPath = path.join(currentDir, "project.json");
+			try {
+				const project = await this.loadProjectConfig(projectJsonPath);
+				if (project) return project;
+			} catch {}
+			currentDir = path.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 = path.isAbsolute(filePath) ? filePath : path.join(this.workspaceRoot, filePath);
+		let currentDir = path.dirname(normalizedPath);
+		while (currentDir !== "/" && currentDir.startsWith(this.workspaceRoot)) {
+			const projectJsonPath = path.join(currentDir, "project.json");
+			try {
+				const project = this.loadProjectConfigSync(projectJsonPath);
+				if (project) return project;
+			} catch {}
+			currentDir = path.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.readFile(projectJsonPath, "utf-8");
+			const config = JSON.parse(content);
+			const projectConfig = {
+				name: config.name || path.basename(path.dirname(projectJsonPath)),
+				root: path.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.readFileSync(projectJsonPath, "utf-8");
+			const config = JSON.parse(content);
+			const projectConfig = {
+				name: config.name || path.basename(path.dirname(projectJsonPath)),
+				root: path.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(path.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 = path.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 = path.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 = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (await fs.pathExists(toolkitConfigPath)) {
+			const yaml = await import("js-yaml");
+			const content = await fs.readFile(toolkitConfigPath, "utf-8");
+			const config = yaml.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;
+				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;
+		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;
+		while (true) {
+			const gitPath = path.join(currentPath, ".git");
+			if (await fs.pathExists(gitPath)) return currentPath;
+			if (currentPath === rootPath) return process.cwd();
+			currentPath = path.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 = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		if (fs.pathExistsSync(toolkitConfigPath)) {
+			const yaml = __require("js-yaml");
+			const content = fs.readFileSync(toolkitConfigPath, "utf-8");
+			const config = yaml.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;
+				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;
+		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;
+		while (true) {
+			const gitPath = path.join(currentPath, ".git");
+			if (fs.pathExistsSync(gitPath)) return currentPath;
+			if (currentPath === rootPath) return process.cwd();
+			currentPath = path.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.pathExists(templatesPath)) return false;
+		return (await fs.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
+export { ProjectFinderService, ScaffoldProcessingService, TemplatesManagerService };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@agiflowai/aicode-utils",
+  "description": "Shared utilities and types for AI-powered code generation, scaffolding, and analysis",
+  "version": "0.4.0",
+  "license": "AGPL-3.0",
+  "author": "AgiflowIO",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgiFlow/aicode-toolkit.git",
+    "directory": "packages/aicode-utils"
+  },
+  "homepage": "https://github.com/AgiFlow/aicode-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/aicode-toolkit/issues"
+  },
+  "keywords": [
+    "typescript",
+    "library",
+    "scaffold",
+    "generator",
+    "template",
+    "boilerplate",
+    "code-generation"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "fs-extra": "11.3.2",
+    "js-yaml": "4.1.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "tsdown": "^0.15.6",
+    "typescript": "5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit"
+  }
+}