@agiflowai/aicode-utils 1.0.8 → 1.0.10

package/dist/index.cjs

@@ -36,6 +36,7 @@ let pino = require("pino");
 pino = __toESM(pino);
 let js_yaml = require("js-yaml");
 js_yaml = __toESM(js_yaml);
+let execa = require("execa");
 let chalk = require("chalk");
 chalk = __toESM(chalk);
 
@@ -92,12 +93,6 @@ 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) {
@@ -140,19 +135,6 @@ 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;
@@ -222,8 +204,7 @@ 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);
@@ -235,12 +216,12 @@ var TemplatesManagerService = class TemplatesManagerService {
 			if (config?.templatesPath) {
 				const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.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 = node_path.default.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
@@ -259,8 +240,7 @@ 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);
@@ -272,12 +252,12 @@ var TemplatesManagerService = class TemplatesManagerService {
 			if (config?.templatesPath) {
 				const templatesPath$1 = node_path.default.isAbsolute(config.templatesPath) ? config.templatesPath : node_path.default.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 = node_path.default.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
@@ -782,6 +762,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 (0, execa.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 (0, execa.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 = node_path.default.resolve(startPath);
+	const rootPath = node_path.default.parse(currentPath).root;
+	while (true) {
+		if (await pathExists(node_path.default.join(currentPath, ".git"))) return currentPath;
+		if (currentPath === rootPath) return null;
+		currentPath = node_path.default.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(node_path.default.join(tempFolder, ".git", "info", "sparse-checkout"), `${subdirectory}\n`);
+		await execGit([
+			"pull",
+			"--depth=1",
+			"origin",
+			"--",
+			branch
+		], tempFolder);
+		const sourceDir = node_path.default.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 = node_path.default.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
 /**
@@ -989,26 +1221,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
 exports.ConfigSource = ConfigSource;
@@ -1018,28 +1230,23 @@ exports.ProjectType = ProjectType;
 exports.ScaffoldProcessingService = ScaffoldProcessingService;
 exports.TemplatesManagerService = TemplatesManagerService;
 exports.accessSync = node_fs.accessSync;
+exports.cloneRepository = cloneRepository;
+exports.cloneSubdirectory = cloneSubdirectory;
 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.fetchGitHubDirectoryContents = fetchGitHubDirectoryContents;
+exports.findWorkspaceRoot = findWorkspaceRoot;
 exports.generateStableId = generateStableId;
+exports.gitInit = gitInit;
 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.parseGitHubUrl = parseGitHubUrl;
 exports.pathExists = pathExists;
 exports.pathExistsSync = pathExistsSync;
 exports.print = print;
@@ -1049,13 +1256,8 @@ 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;
+exports.writeFileSync = node_fs.writeFileSync;

package/dist/index.d.cts

@@ -267,10 +267,9 @@ declare 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 findTemplatesPath(startPath?: string): Promise<string>;
+  static findTemplatesPath(startPath?: string): Promise<string | null>;
   /**
    * Find the workspace root by searching upwards for .git folder
    */
@@ -280,10 +279,9 @@ declare 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?: string): string;
+  static findTemplatesPathSync(startPath?: string): string | null;
   /**
    * Find the workspace root synchronously by searching upwards for .git folder
    */
@@ -353,10 +351,6 @@ 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
  */
@@ -377,31 +371,11 @@ 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/generateStableId.d.ts
 /**
@@ -421,6 +395,130 @@ declare const cp: typeof fs.cp;
  */
 declare function generateStableId(length?: number): string;
 //#endregion
+//#region src/utils/git.d.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.
+ */
+/**
+ * Parsed GitHub URL result
+ */
+interface ParsedGitHubUrl {
+  owner?: string;
+  repo?: string;
+  repoUrl: string;
+  branch?: string;
+  subdirectory?: string;
+  isSubdirectory: boolean;
+}
+/**
+ * GitHub directory entry
+ */
+interface GitHubDirectoryEntry {
+  name: string;
+  type: string;
+  path: string;
+}
+/**
+ * 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
+ */
+declare function gitInit(projectPath: string): Promise<void>;
+/**
+ * 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');
+ * }
+ */
+declare function findWorkspaceRoot(startPath?: string): Promise<string | null>;
+/**
+ * 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
+ */
+declare function parseGitHubUrl(url: string): ParsedGitHubUrl;
+/**
+ * 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'
+ * );
+ */
+declare function cloneSubdirectory(repoUrl: string, branch: string, subdirectory: string, targetFolder: string): Promise<void>;
+/**
+ * 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');
+ */
+declare function cloneRepository(repoUrl: string, targetFolder: string): Promise<void>;
+/**
+ * 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' }, ...]
+ */
+declare function fetchGitHubDirectoryContents(owner: string, repo: string, dirPath: string, branch?: string): Promise<GitHubDirectoryEntry[]>;
+//#endregion
 //#region src/utils/logger.d.ts
 declare const logger: pino.Logger<never, boolean>;
 declare const log: {
@@ -581,21 +679,5 @@ interface ProjectTypeDetectionResult {
  * @returns Detection result with project type and indicators
  */
 declare function detectProjectType(workspaceRoot: string): Promise<ProjectTypeDetectionResult>;
-/**
- * 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
- */
-declare function isMonorepo(workspaceRoot: string): Promise<boolean>;
-/**
- * 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
- */
-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, 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, GeneratorContext, GeneratorFunction, GitHubDirectoryEntry, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedGitHubUrl, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, 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/dist/index.d.mts

@@ -267,10 +267,9 @@ declare 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 findTemplatesPath(startPath?: string): Promise<string>;
+  static findTemplatesPath(startPath?: string): Promise<string | null>;
   /**
    * Find the workspace root by searching upwards for .git folder
    */
@@ -280,10 +279,9 @@ declare 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?: string): string;
+  static findTemplatesPathSync(startPath?: string): string | null;
   /**
    * Find the workspace root synchronously by searching upwards for .git folder
    */
@@ -353,10 +351,6 @@ 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
  */
@@ -377,31 +371,11 @@ 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/generateStableId.d.ts
 /**
@@ -421,6 +395,130 @@ declare const cp: typeof fs.cp;
  */
 declare function generateStableId(length?: number): string;
 //#endregion
+//#region src/utils/git.d.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.
+ */
+/**
+ * Parsed GitHub URL result
+ */
+interface ParsedGitHubUrl {
+  owner?: string;
+  repo?: string;
+  repoUrl: string;
+  branch?: string;
+  subdirectory?: string;
+  isSubdirectory: boolean;
+}
+/**
+ * GitHub directory entry
+ */
+interface GitHubDirectoryEntry {
+  name: string;
+  type: string;
+  path: string;
+}
+/**
+ * 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
+ */
+declare function gitInit(projectPath: string): Promise<void>;
+/**
+ * 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');
+ * }
+ */
+declare function findWorkspaceRoot(startPath?: string): Promise<string | null>;
+/**
+ * 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
+ */
+declare function parseGitHubUrl(url: string): ParsedGitHubUrl;
+/**
+ * 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'
+ * );
+ */
+declare function cloneSubdirectory(repoUrl: string, branch: string, subdirectory: string, targetFolder: string): Promise<void>;
+/**
+ * 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');
+ */
+declare function cloneRepository(repoUrl: string, targetFolder: string): Promise<void>;
+/**
+ * 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' }, ...]
+ */
+declare function fetchGitHubDirectoryContents(owner: string, repo: string, dirPath: string, branch?: string): Promise<GitHubDirectoryEntry[]>;
+//#endregion
 //#region src/utils/logger.d.ts
 declare const logger: pino.Logger<never, boolean>;
 declare const log: {
@@ -581,21 +679,5 @@ interface ProjectTypeDetectionResult {
  * @returns Detection result with project type and indicators
  */
 declare function detectProjectType(workspaceRoot: string): Promise<ProjectTypeDetectionResult>;
-/**
- * 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
- */
-declare function isMonorepo(workspaceRoot: string): Promise<boolean>;
-/**
- * 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
- */
-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, 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, GeneratorContext, GeneratorFunction, type GitHubDirectoryEntry, IFileSystemService, IVariableReplacementService, NxProjectJson, type ParsedGitHubUrl, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, 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/dist/index.mjs

@@ -6,6 +6,7 @@ import { accessSync, mkdirSync, readFileSync, readFileSync as readFileSync$1, st
 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) {
@@ -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;
@@ -195,8 +177,7 @@ 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);
@@ -208,12 +189,12 @@ var TemplatesManagerService = class TemplatesManagerService {
 			if (config?.templatesPath) {
 				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
 				if (await pathExists(templatesPath$1)) return templatesPath$1;
-				else 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);
 		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
@@ -232,8 +213,7 @@ 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);
@@ -245,12 +225,12 @@ var TemplatesManagerService = class TemplatesManagerService {
 			if (config?.templatesPath) {
 				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
 				if (pathExistsSync(templatesPath$1)) return templatesPath$1;
-				else 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);
 		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
@@ -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 = path.resolve(startPath);
+	const rootPath = path.parse(currentPath).root;
+	while (true) {
+		if (await pathExists(path.join(currentPath, ".git"))) return currentPath;
+		if (currentPath === rootPath) return null;
+		currentPath = path.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(path.join(tempFolder, ".git", "info", "sparse-checkout"), `${subdirectory}\n`);
+		await execGit([
+			"pull",
+			"--depth=1",
+			"origin",
+			"--",
+			branch
+		], tempFolder);
+		const sourceDir = path.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 = path.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
 /**
@@ -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.8",
+  "version": "1.0.10",
   "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": {