@agiflowai/aicode-utils 1.0.7 → 1.0.9

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