@agiflowai/aicode-utils 1.0.7 → 1.0.9

package/dist/index.cjs

@@ -6,12 +6,16 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
 	}
 	return to;
 };
@@ -32,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);
 
@@ -88,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) {
@@ -136,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;
@@ -218,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);
@@ -231,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
@@ -255,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);
@@ -268,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
@@ -778,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
 /**
@@ -985,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;
@@ -1014,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;
@@ -1045,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 };