gennady 0.5.0 → 0.5.1-next.1

package/README.md

@@ -20,6 +20,7 @@ npx gennady cat <path1> <path2> ...
 - 🤖 [**Commit Message**](#-commit-messages): Automatically generate clear, descriptive git commit messages from your staged changes.
 - 📝 [**review**](#-review): Instantly review your staged git changes for critical issues (logic, runtime, security).
 - 🐱 [**cat**](#-cat): Quickly display the contents of multiple files or directories at once, filtered by allowed extensions (default: .js, .ts, .tsx).
+- 🛠️ **TypeScript Support**: Full TypeScript type definitions for seamless integration into TypeScript projects.
 
 ---
 
@@ -116,17 +117,69 @@ ollama serve
 Create `~/.gennadyrc` configuration file:
 
 ```json
-[
-    {
-        "url": "https://api.openai.com/v1/chat/completions",
-        "key": "...",
-        "model": "gpt-3.5-turbo-0125"
-    }
-]
+{
+    "models": [
+        {
+            "model": "gpt-3.5-turbo-0125",
+            "url": "https://api.openai.com/v1/chat/completions",
+            "key": "...",
+        },
+        {
+            "model": "llama3:8b",
+            "url": "http://127.0.0.1:11434/api/generate",
+        }
+    ]
+}
 ```
 
 ---
 
+## 🔌 API
+
+Gennady provides a powerful JavaScript/TypeScript API for programmatic usage in your projects.
+
+### Installation
+
+```bash
+npm install gennady
+```
+
+### Basic Usage
+
+```typescript
+import { GennadyRc } from 'gennady/src/rc/rc-config';
+import { AiModel } from 'gennady/src/ai/ai-model';
+
+// Load configuration
+const rc = new GennadyRc();
+
+// Get available AI models
+const models = rc.getModels();
+
+// Create AI model instance
+const aiModel = new AiModel(models[0]);
+
+// Generate text
+const [response, error] = await aiModel.generate('Hello, world!', {
+    temperature: 0.7,
+    timeout: 10000
+});
+
+if (error) {
+    console.error('Error:', error);
+} else {
+    console.log('Response:', response);
+}
+```
+
+### Available Modules
+
+- `AiModel`: Core AI model interaction
+- `GennadyRc`: Configuration management
+- `unguard`: Utility functions for error handling
+
+For complete API documentation, check the source code with detailed JSDoc comments.
+
 ## 🎉 Happy Coding with Gennady!
 
 > Made with 🤖 by Konstantin Lebedev

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './src/ai/ai-model';
+export * from './src/rc/rc-config';
+export * from './src/utils/unguard';

package/index.js

@@ -1,3 +1,7 @@
+export * from './src/ai/ai-model.js';
+export * from './src/rc/rc-config.js';
+export * from './src/utils/unguard.js';
+
 export * from './src/commit-gen/commit-gen.js';
 export * from './src/git/git-diff.js';
 export * from './src/utils/language.js';

package/llm.md

@@ -0,0 +1,82 @@
+# Gennady API: Using AiModel.generate
+
+This guide demonstrates best practices for calling `AiModel.generate` and handling its results, particularly when using TypeScript.
+
+## 1. Basic Usage of `AiModel.generate`
+
+The `AiModel.generate` method returns a Promise that resolves to a tuple: `[result, error]`. You need to handle both potential outcomes.
+
+### ✅ GOOD: Handling the Result Tuple
+
+This example assumes `aiModel` is an initialized instance of `AiModel`.
+
+```typescript
+import { AiModel } from 'gennady/src/ai/ai-model';
+
+async function generateTextWithTupleHandling(aiModel: AiModel, prompt: string) {
+    const [response, error] = await aiModel.generate(prompt, {
+        temperature: 0.7,
+        timeout: 10000, // Optional: timeout in milliseconds
+    });
+    if (error) {
+        throw new Error(`[GENERATE_TEXT_WITH_TUPLE_ERROR] [${aiModel.name}] Generate failed`, {cause: error})
+    }
+
+    return response;
+}
+```
+**Reasoning:** This approach explicitly checks for an error before attempting to use the response. This is the fundamental way to interact with functions designed with this tuple-based error handling pattern.
+
+## 2. Using `AiModel.generate` with `unguardOrThrow` for Cleaner Code
+
+For scenarios where you want to simplify error handling and prefer exceptions for the error path, especially in a sequence of operations, `unguardOrThrow` is recommended.
+
+### ❌ BAD: Multiple Manual Error Checks in Sequential Operations
+
+```typescript
+// ... imports and aiModel initialization ...
+async function sequentialGenerationBad(aiModel: AiModel) {
+    const [response1, error1] = await aiModel.generate("First prompt");
+    if (error1) {
+        throw new Error(`[SEQUENTIAL_GENERATION_BAD_ERROR_1] [${aiModel.name}] Generate failed`, {cause: error1})
+    }
+    console.log("First response:", response1);
+
+    const [response2, error2] = await aiModel.generate("Second prompt using: " + response1.substring(0, 20));
+    if (error2) {
+        throw new Error(`[SEQUENTIAL_GENERATION_BAD_ERROR_2] [${aiModel.name}] Generate failed`, {cause: error2})
+    }
+    console.log("Second response:", response2);
+    // ... and so on
+}
+```
+**Reasoning:** This becomes verbose and repetitive. Each step requires its own error check and handling logic, making the main flow harder to read.
+
+### ✅ GOOD: Using `unguardOrThrow` for Concise Sequential Operations
+
+```typescript
+import { AiModel } from 'gennady/src/ai/ai-model';
+import { unguardOrThrow } from 'gennady/src/utils/unguard';
+
+async function sequentialGenerationGood(aiModel: AiModel) {
+    try {
+        console.log("Attempting first generation...");
+        const response1 = await unguardOrThrow(aiModel.generate("Write a short poem about coding."));
+        console.log("First response:\n", response1);
+
+        console.log("\nAttempting second generation based on the first...");
+        const response2 = await unguardOrThrow(aiModel.generate(`Write a haiku based on this line: "${response1.split('\n')[0]}"`));
+        console.log("Second response (haiku):\n", response2);
+
+        // You can continue the chain of operations here
+        // const response3 = await unguardOrThrow(aiModel.generate(...));
+
+    } catch (error) {
+        throw new Error(`[SEQUENTIAL_GENERATION_GOOD_ERROR] [${aiModel.name}] Generate failed`, {cause: error})
+    }
+}
+```
+**Reasoning:** `unguardOrThrow` unwraps the success value or throws the error if present. This allows you to write cleaner, more linear code for the success path and handle all errors in a single `catch` block. This is particularly useful for chained asynchronous operations where an error at any point should halt the entire chain.
+
+---
+Remember to always initialize `AiModel` with valid configuration, typically loaded via `GennadyRc`. The examples above focus on the `generate` call itself, assuming `aiModel` is ready.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gennady",
-  "version": "0.5.0",
+  "version": "0.5.1-next.1",
   "author": "Konstantin Lebedev <ibnrubaxa@gmail.com>",
   "description": "Gennady — Generate Next-level Automated Description Yntelligence",
   "keywords": [
@@ -19,6 +19,7 @@
   "type": "module",
   "bin": "./cli/gennady.js",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "node --test"
   }

package/src/ai/ai-core.js

@@ -1,14 +1,20 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-const DEFAULT_MODEL = 'llama3:8b';
-const DEFAULT_API_URL = 'http://127.0.0.1:11434/api/generate';
-
-const GENNADY_RC_FILENAME = '.gennadyrc';
+import { AiModel } from './ai-model.js';
+import { GennadyRc } from '../rc/rc-config.js';
+import { unguardOrThrow } from '../utils/unguard.js';
 
+/** @deprecated */
 export class AiCore {
-	api = undefined;
-	apiList = [];
+	/**
+	 * List of AI Models
+	 * @type {AiModel[]} array of #AI_MODEL_CLASS
+	 */
+	#models = [];
+
+	/**
+	 * Active AI Model
+	 * @type {AiModel|null}
+	 */
+	#activeModel = null;
 
 	constructor(init) {
 		this.init = {
@@ -18,39 +24,23 @@ export class AiCore {
 			...init,
 		};
 
-		// Try parse rc files
-		[
-			join(process.cwd(), GENNADY_RC_FILENAME),
-			join(process.env.HOME, GENNADY_RC_FILENAME),
-		].find((file) => {
-			try {
-				if (existsSync(file)) {
-					const items = JSON.parse(readFileSync(file).toString());
-					if (Array.isArray(items)) {
-						this.apiList.push(...items);
-					} else {
-						this.logger.warn(`Invalid "${file}" config:`, items);
-					}
-				}
-			} catch (err) {
-				this.logger.error(`Parse "${file}" error:`, err);
+		GennadyRc.getDefaults().forEach((rc) => {
+			if (rc.isValid()) {
+				this.#models.push(...rc.getModels().map(model => new AiModel(model)));
 			}
 		});
-		
-		// Default API
-		this.apiList[this.init.apiUrl ? 'unshift' : 'push']({
-			url: this.init.url || DEFAULT_API_URL,
-			key: this.init.key,
-			model: this.init.model || DEFAULT_MODEL,
-		});
+
+		if (!this.#models.length) {
+			this.#models.push(AiModel.getDefault());
+		}
 	}
 
 	get model() {
-		return this.api?.model || this.apiList[0].model;
+		return this.#models[0]?.name;
 	}
 
 	get apiUrl() {
-		return this.api?.url || this.apiList[0].url;
+		return this.#models[0]?.url
 	}
 
 	get maxInputTokens() {
@@ -92,96 +82,35 @@ export class AiCore {
 
 	async generate(prompt, context) {
 		try {
-			const api = await this._getApi();
-			if (api.url.includes('completions')) {
-				return await this._callCompletionsApi(api, prompt, context);
-			}
-
-			return await this._callGenerateApi(api, prompt, context);
-		} catch (e) {
-			this.logger.error(`Failed to generate LLM response:`, e);
+			const model = await unguardOrThrow(this.#choiceModel());
+			const result = await unguardOrThrow(model.generate(prompt, context));
+			return result;
+		} catch (error) {
+			this.logger.error(`[AI_CORE_ERROR_GENERATE] Failed to generate LLM response:`, error);
 			return '';
 		}
 	}
 
-	async _getApi() {
-		if (!this.api) {
-			// By default
-			this.api = {url: DEFAULT_API_URL, model: DEFAULT_MODEL};
-
-			for (const api of this.apiList) {
-				try {
-					const ctrl = new AbortController();
-
-					setTimeout(() => ctrl.abort(new Error('Module timeout')), 500);
-
-					const resp = await fetch(api.url, {method: 'HEAD', signal: ctrl.signal});
-					if (resp.status >= 200 && resp.status < 500) {
-						this.api = api;
-						return api;
-					}
-				} catch {}
-			}
-		}
-
-		return this.api;
-	}
-	
-	async _callGenerateApi(api, prompt, context) {
-		const req = await fetch(api.url, {
-			method: 'POST',
-			headers: {'Content-Type': 'application/json'},
-			body: JSON.stringify({
-				model: api.model,
-				stream: false,
-				prompt,
-				context,
-			}),
-		});
-		const data = await req.json();
-		return data.response || '';
-	}
-
-	async _callCompletionsApi(api, prompt, context) {
-		const messages = [];
-		
-		if (context) {
-			messages.push({ role: 'system', content: context });
+	/**
+	 * Choose active model
+	 * @anchor AI_CORE_CHOICE_MODEL
+	 * @returns {Promise<[AiModel, null] | [null, Error]>}
+	 */
+	async #choiceModel() {
+		if (this.#activeModel) {
+			return [this.#activeModel, null];
 		}
 
-		messages.push({ role: 'user', content: prompt });
-
-		const req = await fetch(api.url, {
-			method: 'POST',
-			headers: {
-				'Content-Type': 'application/json',
-				'Authorization': `Bearer ${api.key}`,
-			},
-			body: JSON.stringify({
-				model: api.model,
-				messages: messages,
-				temperature: 0.1,
-				stream: false,
-				timeout: this.init.timeout,
-			}),
-		});
-
-		if (!req.ok) {
-			let errorBody = '';
-			try {
-				errorBody = await req.text();
-			} catch (e) { /* ignore */ }
-
-			throw new Error(`LLM completions request failed with status ${req.status}: ${errorBody}`);
+		for (const model of this.#models) {
+			const [ok, error] = await model.ping();
+			if (ok) {
+				this.#activeModel = model;
+				return [model, null];
+			} else {
+				this.logger.warn(`[AI_CORE_ERROR_PING_MODEL_FAIL] [${model.name}] Ping failed:`, error);
+			}
 		}
 
-		const data = await req.json();
-		
-		if (data.choices && data.choices.length > 0 && data.choices[0].message) {
-			return data.choices[0].message.content || '';
-		} else {
-			this.logger.warn(style.yellow('LLM completions response structure unexpected:'), data);
-			return '';
-		}
+		return [null, new Error(`[AI_CORE_ERROR_PING_FAIL] No available models`)];
 	}
 }

package/src/ai/ai-model.d.ts

@@ -0,0 +1,37 @@
+/** AI Model (LLM) init params #AI_MODEL_INIT */
+export type AiModelInit = {
+    model: string;
+    url: string;
+    key?: string;
+};
+
+/** AI Model (LLM) #AI_MODEL_CLASS */
+export class AiModel {
+    /** Default AI Model #AI_MODEL_DEFAULT */
+    static getDefault(): AiModel;
+
+    /** Constructor #AI_MODEL_CONSTRUCTOR */
+    constructor(init: AiModelInit);
+
+    /** Model identifier/name #AI_MODEL_MODEL_NAME */
+    readonly name: string;
+
+    /** API endpoint URL #AI_MODEL_URL */
+    readonly url: string;
+
+    /** API authentication key #AI_MODEL_KEY */
+    readonly key: string | undefined;
+
+    /** Ping AI Model #AI_MODEL_PING */
+    ping(timeout?: number): Promise<[boolean, null] | [null, Error]>;
+
+    /** Generate LLM response #AI_MODEL_GENERATE */
+    generate(
+        prompt: string,
+        init?: {
+            context?: string;
+            temperature?: number;
+            timeout?: number;
+        }
+    ): Promise<[string, null] | [null, Error]>;
+}

package/src/ai/ai-model.js

@@ -0,0 +1,179 @@
+import { unguardOrThrow } from "../utils/unguard.js";
+
+/**
+ * AI Model (LLM) init params
+ * @SUPER_TOKEN AI_MODEL_INIT
+ * @typedef {Object} AiModelInit
+ * @property {string} model  - Model identifier/name
+ * @property {string} url - API endpoint URL
+ * @property {string} [key] - Optional API authentication key
+ */
+
+/**
+ * AI Model (LLM)
+ * @SUPER_TOKEN AI_MODEL_CLASS
+ */
+export class AiModel {
+	/**
+	 * Default AI Model
+	 * @anchor AI_MODEL_DEFAULT
+	 * @returns {AiModel} #AI_MODEL_CLASS
+	 */
+	static getDefault() {
+		return new AiModel({
+			model: 'llama3:8b',
+			url: 'http://127.0.0.1:11434/api/generate',
+		});
+	}
+
+	/**
+	 * Constructor
+	 * @anchor AI_MODEL_CONSTRUCTOR
+	 * @param {AiModelInit} init - Configuration object (#AI_MODEL_INIT)
+	 */
+	constructor(init) {
+		this.#init = {
+			...this.#init,
+			...init,
+		};
+	}
+
+	/**
+	 * Configuration object
+	 * @type {AiModelInit} #AI_MODEL_INIT
+	 */
+	#init = {};
+
+	/**
+	 * Model identifier/name
+	 * @anchor AI_MODEL_MODEL_NAME
+	 * @returns {string}
+	 */
+	get name() {
+		return this.#init.model;
+	}
+
+	/**
+	 * API endpoint URL
+	 * @anchor AI_MODEL_URL
+	 * @returns {string}
+	 */
+	get url() {
+		return this.#init.url;
+	}
+
+	/**
+	 * API authentication key
+	 * @anchor AI_MODEL_KEY
+	 * @returns {string}
+	 */
+	get key() {
+		return this.#init.key;
+	}
+
+	/**
+	 * Ping AI Model
+	 * @anchor AI_MODEL_PING
+	 * @param {number} [timeout] - Optional ping request timeout
+	 * @returns {Promise<[boolean, null] | [null, Error]>} True if ping successful
+	 */
+	async ping(timeout = 5e3) {
+		try {
+			const answer = await unguardOrThrow(this.generate('Say one token "OK"', {timeout}));
+			return [`${answer}`.toUpperCase() === 'OK', null];
+		} catch (cause) {
+			return [null, new Error(`[AI_MODEL_ERROR_PING] [${this.name}] Ping failed`, {cause})];
+		}
+	}
+
+	/**
+	 * Generate LLM response
+	 * @anchor AI_MODEL_GENERATE
+	 * @param {string} prompt - Prompt text
+	 * @param {Object} [init] - Optional configuration object
+	 * @property {string} [init.context] - Optional context text
+	 * @property {string} [init.temperature] - Optional temperature generation
+	 * @property {string} [init.timeout] - Optional request timeout
+	 * @returns {Promise<[string, null] | [null, Error]>} Generated LLM response
+	 */
+	async generate(prompt, init = {}) {
+		// Prepare fetch params
+		const params = this.url.includes('completions')
+			? {
+				temperature: init.temperature ?? 0.2,
+				messages: [].concat(
+					init.context ? { role: 'system', content: init.context } : [],
+					{ role: 'user', content: prompt },
+				),
+			}
+			: {
+				context: init.context,
+				prompt,
+			}
+		;
+
+		// Call LLM API with params
+		const data = await unguardOrThrow(this.#fetchAsJson(params, init.timeout));
+
+		// Generate API Response
+		if (data && 'response' in data) {
+			return [data.response || '', null];
+		}
+
+		// Completions API Response
+		if (data && data.choices && data.choices.length > 0 && data.choices[0].message) {
+			return [data.choices[0].message.content || '', null];
+		}
+
+		return [null, new Error(
+			`[AI_MODEL_ERROR_GENERATE] [${this.name}] Response structure unexpected`,
+			{cause: data},
+		)];
+	}
+
+	/**
+	 * Fetch data from LLM API
+	 * @anchor AI_MODEL_FETCH_AS_JSON
+	 * @param {Object} params - Request parameters
+	 * @param {number} [timeout] - Optional request timeout
+	 * @returns {Promise<[unknown, null] | [null, Error]>} API response
+	 */
+	async #fetchAsJson(params, timeout = 120e3) {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+		try {
+			const req = await fetch(this.url, {
+				signal: controller.signal,
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					'Authorization': this.key ? `Bearer ${this.key}` : undefined,
+				},
+				body: JSON.stringify({
+					...params,
+					model: this.name,
+					stream: false,
+				}),
+			});
+
+			if (!req.ok) {
+				let errorBody = '';
+				try {
+					errorBody = await req.text();
+				} catch (_) { /* ignore */ }
+				
+				return [null, new Error(
+					`[AI_MODEL_ERROR_FETCH_NOT_OK] [${this.name}] Fetch failed with status "${req.status}"`,
+					{cause: errorBody},
+				)];
+			}
+
+			return [await req.json(), null];
+		} catch (cause) {
+			return [null, new Error(`[AI_MODEL_ERROR_FETCH] [${this.name}] Fetch failed`, {cause})];
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+}

package/src/ai/ai-model.test.js

@@ -0,0 +1,113 @@
+import { describe, test, mock } from 'node:test';
+import assert from 'node:assert';
+import { AiModel } from './ai-model.js';
+
+const defaultInit = {
+    model: 'test-model',
+    url: 'http://localhost/api',
+    key: 'test-key',
+};
+
+describe('AiModel', () => {
+    describe('constructor & getters', () => {
+        test('model, url, key', () => {
+            const ai = new AiModel(defaultInit);
+            assert.strictEqual(ai.name, defaultInit.model);
+            assert.strictEqual(ai.url, defaultInit.url);
+            assert.strictEqual(ai.key, defaultInit.key);
+        });
+    });
+
+    describe('generate()', () => {
+        test('response with .response field', async () => {
+            const mockedFetch = mock.method(global, 'fetch', async () => ({
+                ok: true,
+                json: async () => ({ response: 'hello' })
+            }));
+            try {
+                const ai = new AiModel(defaultInit);
+                const [result, error] = await ai.generate('prompt');
+                assert.strictEqual(error, null);
+                assert.strictEqual(result, 'hello');
+            } finally {
+                mockedFetch.mock.restore();
+            }
+        });
+
+        test('response with choices[0].message', async () => {
+            const mockedFetch = mock.method(global, 'fetch', async () => ({
+                ok: true,
+                json: async () => ({ choices: [{ message: { content: 'hi!' } }] })
+            }));
+            try {
+                const ai = new AiModel({ ...defaultInit, url: 'http://localhost/api/completions' });
+                const [result, error] = await ai.generate('prompt');
+                assert.strictEqual(error, null);
+                assert.strictEqual(result, 'hi!');
+            } finally {
+                mockedFetch.mock.restore();
+            }
+        });
+
+        test('unexpected structure', async () => {
+            const mockedFetch = mock.method(global, 'fetch', async () => ({
+                ok: true,
+                json: async () => ({ foo: 'bar' })
+            }));
+            try {
+                const ai = new AiModel(defaultInit);
+                const [result, error] = await ai.generate('prompt');
+                assert(error instanceof Error);
+                assert.strictEqual(result, null);
+                assert(String(error.message).includes('Response structure unexpected'));
+            } finally {
+                mockedFetch.mock.restore();
+            }
+        });
+    });
+
+    describe('ping()', () => {
+        test('returns true if model responds OK', async () => {
+            const mockedFetch = mock.method(global, 'fetch', async () => ({
+                ok: true,
+                json: async () => ({ response: 'OK' })
+            }));
+            try {
+                const ai = new AiModel(defaultInit);
+                const [ok, err] = await ai.ping();
+                assert.strictEqual(err, null);
+                assert.strictEqual(ok, true);
+            } finally {
+                mockedFetch.mock.restore();
+            }
+        });
+
+        test('returns false if model responds NOT OK', async () => {
+            const mockedFetch = mock.method(global, 'fetch', async () => ({
+                ok: true,
+                json: async () => ({ response: 'NOPE' })
+            }));
+            try {
+                const ai = new AiModel(defaultInit);
+                const [ok, err] = await ai.ping();
+                assert.strictEqual(err, null);
+                assert.strictEqual(ok, false);
+            } finally {
+                mockedFetch.mock.restore();
+            }
+        });
+
+        test('returns error if fetch fails', async () => {
+            const mockedFetch = mock.method(global, 'fetch', async () => { throw new Error('fail'); });
+            try {
+                const ai = new AiModel(defaultInit);
+                const [ok, err] = await ai.ping();
+                assert(err instanceof Error);
+                assert.strictEqual(ok, null);
+                assert(`${err}`.includes('Ping failed'));
+            } finally {
+                mockedFetch.mock.restore();
+            }
+        });
+    });
+});

package/src/git/git-diff.js

@@ -52,6 +52,12 @@ const getCategory = (filename, metadata) => {
 	return category;
 };
 
+/**
+ * Parse git diff
+ * @anchor GIT_DIFF_PARSE
+ * @param {string} diffText - Git diff text
+ * @returns {Object[]} Parsed git diff
+ */
 export const parseGitDiff = (diffText) => {
 	const lines = diffText.split('\n');
 	const result = [];

package/src/rc/rc-config.d.ts

@@ -0,0 +1,30 @@
+/** Gennady RC data #GENNADY_RC_DATA */
+export type RcModel = {
+    model: string;
+    url: string;
+    key?: string;
+};
+
+/** Gennady RC (configuration) #GENNADY_RC_CLASS */
+export class GennadyRc {
+    /** Default Gennady RC filename #GENNADY_RC_DEFAULT_FILENAME */
+    static readonly DEFAULT_FILENAME: string;
+
+    /** Get default rc configs #GENNADY_RC_GET_DEFAULTS */
+    static getDefaults(): GennadyRc[];
+
+    /** Load rc config #GENNADY_RC_LOAD */
+    static load(path?: string): GennadyRc;
+
+    /** Constructor #GENNADY_RC_CONSTRUCTOR */
+    constructor(dir?: string, filename?: string);
+
+    /** Check if config is valid #GENNADY_RC_METHOD_IS_VALID */
+    isValid(): boolean;
+
+    /** Get AI Models config #GENNADY_RC_METHOD_GET_MODELS */
+    getModels(): RcModel[];
+
+    /** Get config parse error #GENNADY_RC_GET_ERROR */
+    getError(): Error | null;
+}

package/src/rc/rc-config.js

@@ -0,0 +1,122 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join as pathJoin } from 'node:path';
+
+/**
+ * Gennady RC data
+ * @SUPER_TOKEN GENNADY_RC_DATA
+ * @typedef {Object} GennadyRcData
+ * @property {AiModelInit[]} models - AI Models configs #AI_MODEL_INIT
+ */
+
+/**
+ * Gennady RC (configuration)
+ * @SUPER_TOKEN GENNADY_RC_CLASS
+ */
+export class GennadyRc {
+	/**
+	 * Default Gennady RC filename
+	 * @anchor GENNADY_RC_DEFAULT_FILENAME
+	 * @constant {string}
+	 */
+	static DEFAULT_FILENAME = '.gennadyrc';
+
+	/**
+	 * Get default rc configs
+	 * @anchor GENNADY_RC_GET_DEFAULTS
+	 * @returns {GennadyRc[]}
+	 */
+	static getDefaults() {
+		return [process.cwd(), process.env.HOME].map((dir) => {
+			return new GennadyRc(dir);
+		});
+	}
+
+	/**
+	 * Config filename
+	 * @anchor GENNADY_RC_FILENAME
+	 * @type {string}
+	 */
+	#filename = '';
+
+	/**
+	 * Config data
+	 * @anchor GENNADY_RC_DATA
+	 * @type {GennadyRcData} #GENNADY_RC_DATA
+	 */
+	#data = {
+		models: [],
+	};
+
+	/**
+	 * Config parse error
+	 * @anchor GENNADY_RC_ERROR
+	 * @type {Error|null}
+	 */
+	#error = null;
+
+	/**
+	 * Constructor
+	 * @anchor GENNADY_RC_CONSTRUCTOR
+	 * @param {string} [dir] - Optional rc-config directory (default process.cwd())
+	 * @param {string} [filename] - Optional rc-config filename (default #GENNADY_RC_FILENAME)
+	 */
+	constructor(
+		dir = process.cwd(),
+		name = GennadyRc.DEFAULT_FILENAME,
+	) {
+		this.#filename = pathJoin(dir, name);
+
+		try {
+			if (existsSync(this.#filename)) {
+				const data = JSON.parse(readFileSync(this.#filename).toString());
+				
+				if (Array.isArray(data)) {
+					// Legacy format
+					this.#data.models = data;
+				} else if (data && Array.isArray(data.models)) {
+					this.#data = {
+						...this.#data,
+						...data,
+					};
+				} else {
+					this.#error = new Error(
+						`[GENNADY_RC_ERROR_CONFIG] Invalid "${this.#filename}" config data`,
+						{cause: data},
+					);
+				}
+			}
+		} catch (err) {
+			this.#error = new Error(
+				`[GENNADY_RC_ERROR_PARSE] Read "${this.#filename}" config failed`,
+				{cause: err},
+			);
+		}
+	}
+
+	/**
+	 * Check if config is valid
+	 * @anchor GENNADY_RC_METHOD_IS_VALID
+	 * @returns {boolean}
+	 */
+	isValid() {
+		return !this.#error;
+	}
+
+	/**
+	 * Get AI Models config
+	 * @anchor GENNADY_RC_METHOD_GET_MODELS
+	 * @returns {AiModelInit[]} array of #AI_MODEL_INIT
+	 */
+	getModels() {
+		return this.#data.models;
+	}
+
+	/**
+	 * Get config parse error
+	 * @anchor GENNADY_RC_GET_ERROR
+	 * @returns {Error|null}
+	 */
+	getError() {
+		return this.#error;
+	}
+}

package/src/rc/rc-config.test.js

@@ -0,0 +1,61 @@
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GennadyRc } from './rc-config.js';
+
+let tempDir;
+
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'gennadyrc-test-'));
+});
+
+afterEach(() => {
+    try {
+        rmSync(tempDir, { recursive: true, force: true });
+    } catch {}
+});
+
+describe('GennadyRC', () => {
+    test('Valid config: object with models', () => {
+        const config = { models: [{ model: 'test-model', url: 'http://localhost' }] };
+        const file = join(tempDir, '.gennadyrc');
+        writeFileSync(file, JSON.stringify(config));
+        const rc = new GennadyRc(tempDir);
+        assert.strictEqual(rc.isValid(), true, 'Config should be valid');
+        assert.deepStrictEqual(rc.getModels(), config.models, 'Models should match');
+    });
+
+    test('Legacy config: array of models', () => {
+        const config = [{ model: 'legacy', url: 'http://legacy' }];
+        const file = join(tempDir, '.gennadyrc');
+        writeFileSync(file, JSON.stringify(config));
+        const rc = new GennadyRc(tempDir);
+        assert.strictEqual(rc.isValid(), true, 'Legacy config should be valid');
+        assert.deepStrictEqual(rc.getModels(), config, 'Legacy models should match');
+    });
+
+    test('Invalid JSON', () => {
+        const file = join(tempDir, '.gennadyrc');
+        writeFileSync(file, '{ invalid json');
+        const rc = new GennadyRc(tempDir);
+        assert.strictEqual(rc.isValid(), false, 'Config with invalid JSON should be invalid');
+        assert(rc.getError() instanceof Error, 'Should have error');
+    });
+
+    test('Invalid structure: object without models', () => {
+        const config = { foo: 'bar' };
+        const file = join(tempDir, '.gennadyrc');
+        writeFileSync(file, JSON.stringify(config));
+        const rc = new GennadyRc(tempDir);
+        assert.strictEqual(rc.isValid(), false, 'Config without models should be invalid');
+        assert(rc.getError() instanceof Error, 'Should have error');
+    });
+
+    test('Missing file', () => {
+        const rc = new GennadyRc(tempDir);
+        assert.strictEqual(rc.isValid(), true, 'Config should be valid if file is missing');
+        assert.deepStrictEqual(rc.getModels(), [], 'Models should be empty if file is missing');
+    });
+});

package/src/review-gen/review-gen.test.js

@@ -5,7 +5,7 @@ import { test, describe } from 'node:test';
 import assert from 'node:assert';
 import { ReviewGen } from './review-gen.js';
 
-describe('review', async () => {
+describe.skip('review', async () => {
 	const reviewGen = new ReviewGen();
 	const fixtures = getFixture();
 

package/src/utils/unguard.d.ts

@@ -0,0 +1,9 @@
+/** Synchronously unwraps a result tuple #UNGUARD_FUNCTION */
+declare function unguard<TResult>(result: [TResult, null] | [null, Error]): TResult;
+
+/** Asynchronously unwraps a result, which can be either a direct tuple `[result, error]` #UNGUARD_OR_THROW_FUNCTION */
+declare function unguardOrThrow<TResult>(
+    resultOrPromise: [TResult, null] | [null, Error] | Promise<[TResult, null] | [null, Error]>
+): Promise<TResult>;
+
+export { unguard, unguardOrThrow };

package/src/utils/unguard.js

@@ -0,0 +1,57 @@
+/**
+ * Synchronously unwraps a result tuple.
+ * If the tuple is malformed or indicates an error (assuming the error is already an Error instance),
+ * this function throws that error. Otherwise, it returns the successful result.
+ *
+ * @template TResult The type of the result expected if the tuple represents a successful outcome.
+ *
+ * @param {unknown} resultTuple - The input, expected to be a tuple `[result, error]`.
+ *   Specifically, `[TResult, null]` for success, or `[null, Error]` for failure.
+ *
+ * @returns {TResult} The unwrapped result if the tuple represents a successful outcome.
+ * @throws {Error} - Throws the error from `resultTuple[1]` if present.
+ *                 - Throws a generic `Error` if `resultTuple` is not a valid 2-element array.
+ */
+
+const unguard = (result) => {
+    if (Array.isArray(result) && result.length === 2) {
+        const error = result[1];
+        
+        if (error === null) {
+            return result[0];
+        } else {
+            throw error instanceof Error
+                ? error
+                : new TypeError(`[UNGUARD_ERROR_TYPE] Error "${error}"`, {cause: error})
+            ;
+        }
+    }
+
+    throw new SyntaxError('[UNGUARD_ERROR_SYNTAX] Invalid input: not a valid [result, error] tuple.', { cause: result });
+}
+
+/**
+ * Asynchronously unwraps a result, which can be either a direct tuple `[result, error]`
+ * or a Promise resolving to such a tuple (typically from `guardedCall`).
+ * If the outcome indicates an error (either directly or after the Promise resolves),
+ * this function throws that error. Otherwise, it returns the successful result.
+ * 
+ * @async
+ * @template TResult The type of the result expected if the operation was successful.
+ *
+ * @param {[TResult, null] | [null, Error] | Promise<([TResult, null] | [null, Error])>} resultOrPromise
+ *   The outcome to unwrap. This can be:
+ *   1. A direct tuple: `[successfulResult, null]`
+ *   2. A direct tuple: `[null, errorInstance]`
+ *   3. A Promise that resolves to one of the above tuples.
+ *
+ * @returns {Promise<TResult>} A Promise that resolves to the unwrapped successful result.
+ * @throws {Error} - Throws the error from the tuple if present (either directly or after
+ *                   the Promise resolves).
+ *                 - Throws a generic `Error` if the resolved value from a Promise is not
+ *                   a valid 2-element `[result, error]` tuple.
+ */
+export const unguardOrThrow = async (resultOrPromise) => {
+    const result = await resultOrPromise;
+    return unguard(result);
+};