@agiflowai/aicode-utils 1.0.7 → 1.0.9

package/dist/index.mjs

@@ -1,11 +1,12 @@
 import { createRequire } from "node:module";
-import * as path$1 from "node:path";
-import path from "node:path";
+import * as path from "node:path";
+import nodePath from "node:path";
 import * as fs from "node:fs/promises";
 import { accessSync, mkdirSync, readFileSync, readFileSync as readFileSync$1, statSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import pino from "pino";
 import * as yaml from "js-yaml";
+import { execa } from "execa";
 import chalk from "chalk";
 
 //#region rolldown:runtime
@@ -65,12 +66,6 @@ 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) {
@@ -89,7 +84,7 @@ async function copy(src, dest) {
 * Move a file or directory
 */
 async function move(src, dest) {
-	await ensureDir(path.dirname(dest));
+	await ensureDir(nodePath.dirname(dest));
 	await fs.rename(src, dest);
 }
 /**
@@ -113,19 +108,6 @@ 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(path.dirname(filePath));
-	await fs.writeFile(filePath, content, "utf-8");
-}
 const readFile = fs.readFile;
 const writeFile = fs.writeFile;
 const readdir = fs.readdir;
@@ -138,12 +120,12 @@ const cp = fs.cp;
 
 //#endregion
 //#region src/utils/logger.ts
-const logsDir = path$1.join(os.tmpdir(), "scaffold-mcp-logs");
+const logsDir = path.join(os.tmpdir(), "scaffold-mcp-logs");
 const logger = pino({
 	level: process.env.LOG_LEVEL || "debug",
 	timestamp: pino.stdTimeFunctions.isoTime
 }, pino.destination({
-	dest: path$1.join(logsDir, "scaffold-mcp.log"),
+	dest: path.join(logsDir, "scaffold-mcp.log"),
 	mkdir: true,
 	sync: true
 }));
@@ -195,36 +177,35 @@ var TemplatesManagerService = class TemplatesManagerService {
 	* 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
+	* @returns The absolute path to the templates directory, or null if not found
 	*/
 	static async findTemplatesPath(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);
 		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);
+				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}`);
+				else return null;
 			}
 		}
-		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
+		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`);
+		return null;
 	}
 	/**
 	* Find the workspace root by searching upwards for .git folder
 	*/
 	static async findWorkspaceRoot(startPath) {
-		let currentPath = path.resolve(startPath);
-		const rootPath = path.parse(currentPath).root;
+		let currentPath = nodePath.resolve(startPath);
+		const rootPath = nodePath.parse(currentPath).root;
 		while (true) {
-			if (await pathExists(path.join(currentPath, ".git"))) return currentPath;
+			if (await pathExists(nodePath.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
-			currentPath = path.dirname(currentPath);
+			currentPath = nodePath.dirname(currentPath);
 		}
 	}
 	/**
@@ -232,36 +213,35 @@ var TemplatesManagerService = class TemplatesManagerService {
 	* 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
+	* @returns The absolute path to the templates directory, or null if not found
 	*/
 	static findTemplatesPathSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		const toolkitConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		if (pathExistsSync(toolkitConfigPath)) {
 			const yaml$1 = __require("js-yaml");
 			const content = readFileSync$1(toolkitConfigPath, "utf-8");
 			const config = yaml$1.load(content);
 			if (config?.templatesPath) {
-				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
+				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}`);
+				else return null;
 			}
 		}
-		const templatesPath = path.join(workspaceRoot, TemplatesManagerService.TEMPLATES_FOLDER);
+		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`);
+		return null;
 	}
 	/**
 	* Find the workspace root synchronously by searching upwards for .git folder
 	*/
 	static findWorkspaceRootSync(startPath) {
-		let currentPath = path.resolve(startPath);
-		const rootPath = path.parse(currentPath).root;
+		let currentPath = nodePath.resolve(startPath);
+		const rootPath = nodePath.parse(currentPath).root;
 		while (true) {
-			if (pathExistsSync(path.join(currentPath, ".git"))) return currentPath;
+			if (pathExistsSync(nodePath.join(currentPath, ".git"))) return currentPath;
 			if (currentPath === rootPath) return process.cwd();
-			currentPath = path.dirname(currentPath);
+			currentPath = nodePath.dirname(currentPath);
 		}
 	}
 	/**
@@ -294,7 +274,7 @@ 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);
+		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");
@@ -308,7 +288,7 @@ var TemplatesManagerService = class TemplatesManagerService {
 	*/
 	static readToolkitConfigSync(startPath = process.cwd()) {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
-		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
+		const toolkitConfigPath = nodePath.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		if (!pathExistsSync(toolkitConfigPath)) return null;
 		const yaml$1 = __require("js-yaml");
 		const content = readFileSync$1(toolkitConfigPath, "utf-8");
@@ -322,7 +302,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");
 	}
@@ -393,13 +373,13 @@ var ProjectConfigResolver = class ProjectConfigResolver {
 	*/
 	static async resolveProjectConfig(projectPath, explicitTemplate) {
 		try {
-			const absolutePath = path.resolve(projectPath);
+			const absolutePath = nodePath.resolve(projectPath);
 			if (explicitTemplate) return {
 				type: ProjectType.MONOLITH,
 				sourceTemplate: explicitTemplate,
 				configSource: ConfigSource.TOOLKIT_YAML
 			};
-			const projectJsonPath = path.join(absolutePath, "project.json");
+			const projectJsonPath = nodePath.join(absolutePath, "project.json");
 			if (await pathExists(projectJsonPath)) {
 				const projectJson = await readJson(projectJsonPath);
 				if (projectJson.sourceTemplate && typeof projectJson.sourceTemplate === "string" && projectJson.sourceTemplate.trim()) return {
@@ -490,12 +470,12 @@ Run 'scaffold-mcp scaffold list --help' for more info.`;
 	* @param sourceTemplate - The template identifier
 	*/
 	static async createProjectJson(projectPath, projectName, sourceTemplate) {
-		const projectJsonPath = path.join(projectPath, "project.json");
+		const projectJsonPath = nodePath.join(projectPath, "project.json");
 		try {
 			let projectJson;
 			if (await pathExists(projectJsonPath)) projectJson = await readJson(projectJsonPath);
 			else {
-				const relativePath = path.relative(projectPath, process.cwd());
+				const relativePath = nodePath.relative(projectPath, process.cwd());
 				projectJson = {
 					name: projectName,
 					$schema: relativePath ? `${relativePath}/node_modules/nx/schemas/project-schema.json` : "node_modules/nx/schemas/project-schema.json",
@@ -547,15 +527,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;
 	}
@@ -566,15 +546,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;
 	}
@@ -587,8 +567,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
 			};
@@ -607,8 +587,8 @@ var ProjectFinderService = class {
 			const content = readFileSync$1(projectJsonPath, "utf-8");
 			const config = JSON.parse(content);
 			const projectConfig = {
-				name: config.name || path.basename(path.dirname(projectJsonPath)),
-				root: path.dirname(projectJsonPath),
+				name: config.name || nodePath.basename(nodePath.dirname(projectJsonPath)),
+				root: nodePath.dirname(projectJsonPath),
 				sourceTemplate: config.sourceTemplate,
 				projectType: config.projectType
 			};
@@ -668,7 +648,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;
@@ -690,7 +670,7 @@ var ScaffoldProcessingService = class {
 		}
 		for (const item of items) {
 			if (!item) continue;
-			const itemPath = path.join(dirPath, item);
+			const itemPath = nodePath.join(dirPath, item);
 			try {
 				const stat$1 = await this.fileSystem.stat(itemPath);
 				if (stat$1.isDirectory()) await this.trackCreatedFilesRecursive(itemPath, createdFiles);
@@ -713,7 +693,7 @@ var ScaffoldProcessingService = class {
 		}
 		for (const item of items) {
 			if (!item) continue;
-			const itemPath = path.join(dirPath, item);
+			const itemPath = nodePath.join(dirPath, item);
 			try {
 				const stat$1 = await this.fileSystem.stat(itemPath);
 				if (stat$1.isDirectory()) await this.trackExistingFilesRecursive(itemPath, existingFiles);
@@ -755,6 +735,258 @@ function generateStableId(length = 8) {
 	return result;
 }
 
+//#endregion
+//#region src/utils/git.ts
+/**
+* Git Utilities
+*
+* DESIGN PATTERNS:
+* - Safe command execution: Use execa with array arguments to prevent shell injection
+* - Defense in depth: Use '--' separator to prevent option injection attacks
+*
+* CODING STANDARDS:
+* - All git commands must use execGit helper with array arguments
+* - Use '--' separator before user-provided arguments (URLs, branches, paths)
+* - Validate inputs where appropriate
+*
+* AVOID:
+* - Shell string interpolation
+* - Passing unsanitized user input as command options
+*
+* NOTE: These utilities perform I/O operations (git commands, file system) by necessity.
+* Pure utility functions like parseGitHubUrl are side-effect free.
+*/
+/**
+* Type guard to check if an error has the expected execa error shape
+* @param error - The error to check
+* @returns True if the error has message property (and optionally stderr)
+* @example
+* try {
+*   await execa('git', ['status']);
+* } catch (error) {
+*   if (isExecaError(error)) {
+*     console.error(error.stderr || error.message);
+*   }
+* }
+*/
+function isExecaError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (!("message" in error)) return false;
+	return typeof error.message === "string";
+}
+/**
+* Execute a git command safely using execa to prevent command injection
+* @param args - Array of git command arguments
+* @param cwd - Optional working directory for the command
+* @throws Error when git command fails
+*/
+async function execGit(args, cwd) {
+	try {
+		await execa("git", args, { cwd });
+	} catch (error) {
+		if (isExecaError(error)) throw new Error(`Git command failed: ${error.stderr || error.message}`);
+		throw error;
+	}
+}
+/**
+* Execute git init safely using execa to prevent command injection
+* Uses '--' to prevent projectPath from being interpreted as an option
+* @param projectPath - Path where to initialize the git repository
+* @throws Error when git init fails
+*/
+async function gitInit(projectPath) {
+	try {
+		await execa("git", [
+			"init",
+			"--",
+			projectPath
+		]);
+	} catch (error) {
+		if (isExecaError(error)) throw new Error(`Git init failed: ${error.stderr || error.message}`);
+		throw error;
+	}
+}
+/**
+* Find the workspace root by searching upwards for .git folder
+* Returns null if no .git folder is found (indicating a new project setup is needed)
+* @param startPath - The path to start searching from (default: current working directory)
+* @returns The workspace root path or null if not in a git repository
+* @example
+* const root = await findWorkspaceRoot('/path/to/project/src');
+* if (root) {
+*   console.log('Workspace root:', root);
+* } else {
+*   console.log('No git repository found');
+* }
+*/
+async function findWorkspaceRoot(startPath = process.cwd()) {
+	let currentPath = nodePath.resolve(startPath);
+	const rootPath = nodePath.parse(currentPath).root;
+	while (true) {
+		if (await pathExists(nodePath.join(currentPath, ".git"))) return currentPath;
+		if (currentPath === rootPath) return null;
+		currentPath = nodePath.dirname(currentPath);
+	}
+}
+/**
+* Parse GitHub URL to detect if it's a subdirectory
+* Supports formats:
+* - https://github.com/user/repo
+* - https://github.com/user/repo/tree/branch/path/to/dir
+* - https://github.com/user/repo/tree/main/path/to/dir
+* @param url - The GitHub URL to parse
+* @returns Parsed URL components including owner, repo, branch, and subdirectory
+* @example
+* const result = parseGitHubUrl('https://github.com/user/repo/tree/main/src');
+* // result.owner === 'user'
+* // result.repo === 'repo'
+* // result.branch === 'main'
+* // result.subdirectory === 'src'
+* // result.isSubdirectory === true
+*/
+function parseGitHubUrl(url) {
+	const treeMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+)$/);
+	const blobMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/);
+	const rootMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (treeMatch || blobMatch) {
+		const match = treeMatch || blobMatch;
+		return {
+			owner: match?.[1],
+			repo: match?.[2],
+			repoUrl: `https://github.com/${match?.[1]}/${match?.[2]}.git`,
+			branch: match?.[3],
+			subdirectory: match?.[4],
+			isSubdirectory: true
+		};
+	}
+	if (rootMatch) return {
+		owner: rootMatch[1],
+		repo: rootMatch[2],
+		repoUrl: `https://github.com/${rootMatch[1]}/${rootMatch[2]}.git`,
+		isSubdirectory: false
+	};
+	return {
+		repoUrl: url,
+		isSubdirectory: false
+	};
+}
+/**
+* Clone a subdirectory from a git repository using sparse checkout
+* Uses '--' to mark end of options - prevents malicious URLs like '--upload-pack=evil'
+* from being interpreted as git options
+* @param repoUrl - The git repository URL
+* @param branch - The branch to clone from
+* @param subdirectory - The subdirectory path within the repository
+* @param targetFolder - The local folder to clone into
+* @throws Error if subdirectory not found or target folder already exists
+* @example
+* await cloneSubdirectory(
+*   'https://github.com/user/repo.git',
+*   'main',
+*   'packages/core',
+*   './my-project'
+* );
+*/
+async function cloneSubdirectory(repoUrl, branch, subdirectory, targetFolder) {
+	const tempFolder = `${targetFolder}.tmp`;
+	try {
+		await execGit([
+			"init",
+			"--",
+			tempFolder
+		]);
+		await execGit([
+			"remote",
+			"add",
+			"origin",
+			"--",
+			repoUrl
+		], tempFolder);
+		await execGit([
+			"config",
+			"core.sparseCheckout",
+			"true"
+		], tempFolder);
+		await writeFile(nodePath.join(tempFolder, ".git", "info", "sparse-checkout"), `${subdirectory}\n`);
+		await execGit([
+			"pull",
+			"--depth=1",
+			"origin",
+			"--",
+			branch
+		], tempFolder);
+		const sourceDir = nodePath.join(tempFolder, subdirectory);
+		if (!await pathExists(sourceDir)) throw new Error(`Subdirectory '${subdirectory}' not found in repository at branch '${branch}'`);
+		if (await pathExists(targetFolder)) throw new Error(`Target folder already exists: ${targetFolder}`);
+		await move(sourceDir, targetFolder);
+		await remove(tempFolder);
+	} catch (error) {
+		if (await pathExists(tempFolder)) await remove(tempFolder);
+		throw error;
+	}
+}
+/**
+* Clone entire repository
+* Uses '--' to mark end of options - prevents malicious URLs like '--upload-pack=evil'
+* from being interpreted as git options
+* @param repoUrl - The git repository URL to clone
+* @param targetFolder - The local folder path to clone into
+* @throws Error if git clone fails
+* @example
+* await cloneRepository('https://github.com/user/repo.git', './my-project');
+*/
+async function cloneRepository(repoUrl, targetFolder) {
+	await execGit([
+		"clone",
+		"--",
+		repoUrl,
+		targetFolder
+	]);
+	const gitFolder = nodePath.join(targetFolder, ".git");
+	if (await pathExists(gitFolder)) await remove(gitFolder);
+}
+/**
+* Type guard to validate GitHub API content item structure
+* @param item - The item to validate
+* @returns True if the item has required GitHubContentItem properties
+*/
+function isGitHubContentItem(item) {
+	if (typeof item !== "object" || item === null) return false;
+	const obj = item;
+	return typeof obj.name === "string" && typeof obj.type === "string" && typeof obj.path === "string";
+}
+/**
+* Fetch directory listing from GitHub API
+* @param owner - The GitHub repository owner/organization
+* @param repo - The repository name
+* @param dirPath - The directory path within the repository
+* @param branch - The branch to fetch from (default: 'main')
+* @returns Array of directory entries with name, type, and path
+* @throws Error if the API request fails or returns non-directory content
+* @remarks
+* - Requires network access to GitHub API
+* - Subject to GitHub API rate limits (60 requests/hour unauthenticated)
+* - Only works with public repositories without authentication
+* @example
+* const contents = await fetchGitHubDirectoryContents('facebook', 'react', 'packages', 'main');
+* // contents: [{ name: 'react', type: 'dir', path: 'packages/react' }, ...]
+*/
+async function fetchGitHubDirectoryContents(owner, repo, dirPath, branch = "main") {
+	const url = `https://api.github.com/repos/${owner}/${repo}/contents/${dirPath}?ref=${branch}`;
+	const response = await fetch(url, { headers: {
+		Accept: "application/vnd.github.v3+json",
+		"User-Agent": "scaffold-mcp"
+	} });
+	if (!response.ok) throw new Error(`Failed to fetch directory contents: ${response.statusText}`);
+	const data = await response.json();
+	if (!Array.isArray(data)) throw new Error("Expected directory but got file");
+	return data.filter(isGitHubContentItem).map((item) => ({
+		name: item.name,
+		type: item.type,
+		path: item.path
+	}));
+}
+
 //#endregion
 //#region src/utils/print.ts
 /**
@@ -927,7 +1159,7 @@ const MONOREPO_INDICATOR_FILES = [
 */
 async function detectProjectType(workspaceRoot) {
 	const indicators = [];
-	const toolkitYamlPath = path.join(workspaceRoot, "toolkit.yaml");
+	const toolkitYamlPath = nodePath.join(workspaceRoot, "toolkit.yaml");
 	if (await pathExists(toolkitYamlPath)) try {
 		const content = await fs.readFile(toolkitYamlPath, "utf-8");
 		const config = yaml.load(content);
@@ -939,14 +1171,14 @@ async function detectProjectType(workspaceRoot) {
 			};
 		}
 	} catch {}
-	for (const filename of MONOREPO_INDICATOR_FILES) if (await pathExists(path.join(workspaceRoot, filename))) {
+	for (const filename of MONOREPO_INDICATOR_FILES) if (await pathExists(nodePath.join(workspaceRoot, filename))) {
 		indicators.push(`${filename} found`);
 		return {
 			projectType: ProjectType.MONOREPO,
 			indicators
 		};
 	}
-	const packageJsonPath = path.join(workspaceRoot, "package.json");
+	const packageJsonPath = nodePath.join(workspaceRoot, "package.json");
 	if (await pathExists(packageJsonPath)) try {
 		if ((await readJson(packageJsonPath)).workspaces) {
 			indicators.push("package.json with workspaces found");
@@ -962,26 +1194,6 @@ async function detectProjectType(workspaceRoot) {
 		indicators
 	};
 }
-/**
-* Check if a workspace is a monorepo
-* Convenience function that returns a boolean
-*
-* @param workspaceRoot - Absolute path to the workspace root directory
-* @returns True if workspace is detected as monorepo, false otherwise
-*/
-async function isMonorepo(workspaceRoot) {
-	return (await detectProjectType(workspaceRoot)).projectType === ProjectType.MONOREPO;
-}
-/**
-* Check if a workspace is a monolith
-* Convenience function that returns a boolean
-*
-* @param workspaceRoot - Absolute path to the workspace root directory
-* @returns True if workspace is detected as monolith, false otherwise
-*/
-async function isMonolith(workspaceRoot) {
-	return (await detectProjectType(workspaceRoot)).projectType === ProjectType.MONOLITH;
-}
 
 //#endregion
-export { ConfigSource, ProjectConfigResolver, ProjectFinderService, ProjectType, ScaffoldProcessingService, TemplatesManagerService, accessSync, copy, cp, detectProjectType, ensureDir, ensureDirSync, fs, generateStableId, 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 };
+export { ConfigSource, ProjectConfigResolver, ProjectFinderService, ProjectType, ScaffoldProcessingService, TemplatesManagerService, accessSync, cloneRepository, cloneSubdirectory, copy, detectProjectType, ensureDir, fetchGitHubDirectoryContents, findWorkspaceRoot, generateStableId, gitInit, icons, log, logger, messages, mkdir, mkdirSync, move, parseGitHubUrl, pathExists, pathExistsSync, print, readFile, readFileSync, readJson, readJsonSync, readdir, remove, sections, stat, statSync, writeFile, writeFileSync };

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.7",
+  "version": "1.0.9",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {
@@ -31,7 +31,8 @@
   ],
   "dependencies": {
     "chalk": "5.6.2",
-    "js-yaml": "4.1.0",
+    "execa": "^9.5.2",
+    "js-yaml": "4.1.1",
     "ora": "^9.0.0",
     "pino": "^10.0.0"
   },
@@ -43,7 +44,7 @@
     "chance": "^1.1.13",
     "tsdown": "^0.16.4",
     "typescript": "5.9.3",
-    "vitest": "^3.0.0"
+    "vitest": "4.0.15"
   },
   "type": "module",
   "publishConfig": {