feat(core): enhance error handling, type safety, and documentation

- Add comprehensive error handling with try/catch blocks and meaningful error messages
- Improve type safety with proper IEnvDeps interface replacing 'any' types
- Add complete JSDoc documentation for all classes and methods
- Add return type annotations for better TypeScript support
- Add ensureInitialized() validation method
- Fix missing return statement in createRepoByClone() method
- Remove deprecated @types/minimatch dependency
- Complete readme rewrite with modern styling, accurate documentation, and proper API examples
- Update license from LICENSE to license.md following project guidelines

ts/smartgit.classes.smartgit.ts

@@ -1,40 +1,90 @@
 import * as plugins from './smartgit.plugins.js';
 import { GitRepo } from './smartgit.classes.gitrepo.js';
 
+interface IEnvDeps {
+  fs: typeof import('fs') | null;
+  http: any | null; // isomorphic-git http interface
+}
+
+/**
+ * class Smartgit provides a high-level interface for git operations
+ * Must be initialized before use by calling init()
+ */
 export class Smartgit {
   public smartenvInstance = new plugins.smartenv.Smartenv();
-  public envDeps: {
-    fs: any;
-    http: any;
-  } = {
+  public envDeps: IEnvDeps = {
     fs: null,
     http: null,
   };
 
-  constructor() {}
-
-  public async init() {
-    if (this.smartenvInstance.isNode) {
-      this.envDeps.fs = await this.smartenvInstance.getSafeNodeModule('fs');
-      this.envDeps.http = await this.smartenvInstance.getSafeNodeModule(
-        'isomorphic-git/http/node'
-      );
-    } else {
-      throw new Error('currently only node.js is supported.');
+  /**
+   * initializes the Smartgit instance with required environment dependencies
+   * Must be called before using any repository methods
+   */
+  public async init(): Promise<void> {
+    try {
+      if (this.smartenvInstance.isNode) {
+        this.envDeps.fs = await this.smartenvInstance.getSafeNodeModule('fs');
+        this.envDeps.http = await this.smartenvInstance.getSafeNodeModule(
+          'isomorphic-git/http/node'
+        );
+      } else {
+        throw new Error('currently only node.js is supported.');
+      }
+    } catch (error) {
+      throw new Error(`Failed to initialize Smartgit: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
 
-  public async createRepoByClone(fromUrlArg: string, toDirArg: string) {
-    const repo = await GitRepo.fromCloningIntoDir(this, fromUrlArg, toDirArg);
+  private ensureInitialized(): void {
+    if (!this.envDeps.fs || !this.envDeps.http) {
+      throw new Error('Smartgit must be initialized before use. Call init() first.');
+    }
   }
 
-  public async createRepoByInit(dirArg: string) {
-    const repo = await GitRepo.fromCreatingRepoInDir(this, dirArg);
-    return repo;
+  /**
+   * creates a new GitRepo instance by cloning from a remote URL
+   * @param fromUrlArg the URL to clone from
+   * @param toDirArg the directory to clone into
+   * @returns Promise<GitRepo> the created repository instance
+   */
+  public async createRepoByClone(fromUrlArg: string, toDirArg: string): Promise<GitRepo> {
+    this.ensureInitialized();
+    try {
+      const repo = await GitRepo.fromCloningIntoDir(this, fromUrlArg, toDirArg);
+      return repo;
+    } catch (error) {
+      throw new Error(`Failed to clone repository: ${error instanceof Error ? error.message : String(error)}`);
+    }
   }
 
-  public async createRepoByOpen(dirArg: string) {
-    const repo = await GitRepo.fromOpeningRepoDir(this, dirArg);
-    return repo;
+  /**
+   * creates a new GitRepo instance by initializing a new repository in a directory
+   * @param dirArg the directory to initialize the repository in
+   * @returns Promise<GitRepo> the created repository instance
+   */
+  public async createRepoByInit(dirArg: string): Promise<GitRepo> {
+    this.ensureInitialized();
+    try {
+      const repo = await GitRepo.fromCreatingRepoInDir(this, dirArg);
+      return repo;
+    } catch (error) {
+      throw new Error(`Failed to initialize repository: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * creates a new GitRepo instance by opening an existing repository in a directory
+   * @param dirArg the directory containing the existing repository
+   * @returns Promise<GitRepo> the opened repository instance
+   */
+  public async createRepoByOpen(dirArg: string): Promise<GitRepo> {
+    this.ensureInitialized();
+    try {
+      const repo = await GitRepo.fromOpeningRepoDir(this, dirArg);
+      return repo;
+    } catch (error) {
+      throw new Error(`Failed to open repository: ${error instanceof Error ? error.message : String(error)}`);
+    }
   }
 }