@nexical/ai 0.1.0

package/.github/workflows/deploy.yml

@@ -0,0 +1,34 @@
+name: Deploy Nexical AI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    name: Build & Publish
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install Dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm run test
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx lint-staged

package/dist/AiClientFactory.js

@@ -0,0 +1,10 @@
+import { GeminiCLI } from './providers/GeminiCLI.js';
+export class AiClientFactory {
+    static create(config) {
+        const provider = config?.provider || 'gemini-cli';
+        if (provider === 'gemini-cli') {
+            return new GeminiCLI(config || {});
+        }
+        throw new Error(`Unsupported AI Client provider: ${provider}`);
+    }
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './providers/GeminiCLI.js';
+export * from './AiClientFactory.js';

package/dist/providers/GeminiCLI.js

@@ -0,0 +1,52 @@
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+export class GeminiCLI {
+    commandTemplate;
+    constructor(config) {
+        this.commandTemplate = config.commandTemplate || 'gemini --yolo -p "" --model {model}';
+    }
+    run(model, input) {
+        return new Promise((resolve) => {
+            const command = this.commandTemplate.replace('{model}', model);
+            const start = Date.now();
+            const child = spawn(command, {
+                shell: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdoutData = '';
+            let stderrData = '';
+            child.stdout?.on('data', (data) => {
+                const chunk = data.toString();
+                process.stdout.write(chalk.yellow(chunk));
+                stdoutData += chunk;
+            });
+            child.stderr?.on('data', (data) => {
+                const chunk = data.toString();
+                stderrData += chunk;
+            });
+            child.stdin.write(input);
+            child.stdin.end();
+            child.on('close', (code) => {
+                const duration = Date.now() - start;
+                const exitCode = code ?? 1;
+                const isExhausted = stderrData.includes('429') ||
+                    stderrData.includes('exhausted your capacity') ||
+                    stderrData.includes('ResourceExhausted');
+                if (exitCode !== 0 && isExhausted) {
+                    console.warn(`[Agent] Model ${model} exhausted (429). Duration: ${duration}ms`);
+                    resolve({ code: exitCode, shouldRetry: true, output: stdoutData });
+                }
+                else {
+                    if (exitCode !== 0 && stderrData) {
+                        process.stderr.write(stderrData);
+                    }
+                    resolve({ code: exitCode, shouldRetry: false, output: stdoutData });
+                }
+            });
+            child.on('error', (err) => {
+                console.error(`[Agent] Failed to spawn Gemini (${model}): ${err instanceof Error ? err.message : String(err)}`);
+                resolve({ code: 1, shouldRetry: false, output: '' });
+            });
+        });
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/eslint.config.mjs

@@ -0,0 +1,67 @@
+import eslintPluginAstro from 'eslint-plugin-astro';
+import eslintPluginReact from 'eslint-plugin-react';
+import eslintPluginReactHooks from 'eslint-plugin-react-hooks';
+import eslintPluginJsxA11y from 'eslint-plugin-jsx-a11y';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+import js from '@eslint/js';
+
+export default tseslint.config(
+  // Global ignore
+  {
+    ignores: ['**/dist/**', '**/node_modules/**', '**/coverage/**', '**/.astro/**', '**/.agent/**'],
+  },
+
+  // Base JS/TS configuration
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+
+  // React configuration
+  {
+    files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}'],
+    plugins: {
+      react: eslintPluginReact,
+      'react-hooks': eslintPluginReactHooks,
+      'jsx-a11y': eslintPluginJsxA11y,
+    },
+    languageOptions: {
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      },
+    },
+    rules: {
+      ...eslintPluginReact.configs.recommended.rules,
+      ...eslintPluginReactHooks.configs.recommended.rules,
+      ...eslintPluginJsxA11y.configs.recommended.rules,
+      'react/react-in-jsx-scope': 'off', // Not needed in React 17+ or Astro
+      'react/no-unknown-property': 'off', // Conflicts with some Astro/Web Component patterns
+    },
+  },
+
+  // Astro configuration
+  ...eslintPluginAstro.configs.recommended,
+
+  // Custom rules override
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { args: 'none', varsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'warn', // Downgrade to warning for now as codebase has some anys
+      'no-console': ['warn', { allow: ['warn', 'error', 'info'] }],
+    },
+  },
+
+  // Prettier must be last to override conflicting rules
+  eslintConfigPrettier,
+);

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@nexical/ai",
+    "version": "0.1.0",
+    "description": "General purpose AI Client interfaces and providers for the Nexical applications",
+    "type": "module",
+    "main": "dist/index.js",
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "format": "prettier --write .",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "prepare": "husky",
+        "prepublishOnly": "npm run build",
+        "test": "vitest run --passWithNoTests",
+        "test:unit": "vitest run --passWithNoTests"
+    },
+    "lint-staged": {
+        "**/*": [
+            "prettier --write --ignore-unknown"
+        ],
+        "**/*.{js,jsx,ts,tsx,astro}": [
+            "eslint --fix"
+        ]
+    },
+    "dependencies": {
+        "chalk": "^5.3.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "@types/node": "^22.0.0",
+        "eslint": "^9.39.2",
+        "eslint-config-prettier": "^10.0.1",
+        "globals": "^15.9.0",
+        "husky": "^9.1.5",
+        "lint-staged": "^15.2.10",
+        "prettier": "^3.3.3",
+        "typescript": "^5.5.4",
+        "typescript-eslint": "^8.3.0",
+        "vitest": "^2.1.0"
+    },
+    "types": "dist/index.d.ts"
+}

package/src/AiClientFactory.ts

@@ -0,0 +1,14 @@
+import { AiClient, AiClientConfig } from './types.js';
+import { GeminiCLI } from './providers/GeminiCLI.js';
+
+export class AiClientFactory {
+    static create(config?: AiClientConfig): AiClient {
+        const provider = config?.provider || 'gemini-cli';
+
+        if (provider === 'gemini-cli') {
+            return new GeminiCLI(config || {});
+        }
+
+        throw new Error(`Unsupported AI Client provider: ${provider}`);
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './providers/GeminiCLI.js';
+export * from './AiClientFactory.js';

package/src/providers/GeminiCLI.ts

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import { AiClient, AiClientConfig, AiClientResult } from '../types.js';
+
+export class GeminiCLI implements AiClient {
+    private commandTemplate: string;
+
+    constructor(config: AiClientConfig) {
+        this.commandTemplate = config.commandTemplate || 'gemini --yolo -p "" --model {model}';
+    }
+
+    run(model: string, input: string): Promise<AiClientResult> {
+        return new Promise((resolve) => {
+            const command = this.commandTemplate.replace('{model}', model);
+            const start = Date.now();
+
+            const child = spawn(command, {
+                shell: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+
+            let stdoutData = '';
+            let stderrData = '';
+
+            child.stdout?.on('data', (data) => {
+                const chunk = data.toString();
+                process.stdout.write(chalk.yellow(chunk));
+                stdoutData += chunk;
+            });
+
+            child.stderr?.on('data', (data) => {
+                const chunk = data.toString();
+                stderrData += chunk;
+            });
+
+            child.stdin.write(input);
+            child.stdin.end();
+
+            child.on('close', (code) => {
+                const duration = Date.now() - start;
+                const exitCode = code ?? 1;
+                const isExhausted =
+                    stderrData.includes('429') ||
+                    stderrData.includes('exhausted your capacity') ||
+                    stderrData.includes('ResourceExhausted');
+
+                if (exitCode !== 0 && isExhausted) {
+                    console.warn(`[Agent] Model ${model} exhausted (429). Duration: ${duration}ms`);
+                    resolve({ code: exitCode, shouldRetry: true, output: stdoutData });
+                } else {
+                    if (exitCode !== 0 && stderrData) {
+                        process.stderr.write(stderrData);
+                    }
+                    resolve({ code: exitCode, shouldRetry: false, output: stdoutData });
+                }
+            });
+
+            child.on('error', (err) => {
+                console.error(
+                    `[Agent] Failed to spawn Gemini (${model}): ${err instanceof Error ? err.message : String(err)}`,
+                );
+                resolve({ code: 1, shouldRetry: false, output: '' });
+            });
+        });
+    }
+}

package/src/types.ts

@@ -0,0 +1,15 @@
+export interface AiClientResult {
+    code: number;
+    shouldRetry: boolean;
+    output: string;
+}
+
+export interface AiClientConfig {
+    provider?: string;
+    commandTemplate?: string;
+    [key: string]: unknown;
+}
+
+export interface AiClient {
+    run(model: string, input: string): Promise<AiClientResult>;
+}

package/tests/providers/GeminiCLI.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GeminiCLI } from '../../src/providers/GeminiCLI.js';
+import { spawn } from 'node:child_process';
+
+vi.mock('node:child_process', () => ({
+    spawn: vi.fn(),
+}));
+
+describe('GeminiCLI', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        // Prevent stdout/stderr intercepts from breaking the test output
+        vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    });
+
+    it('should run a prompt and succeed', async () => {
+        const mockChild = {
+            stdout: { on: vi.fn((event, cb) => cb('mock response')) },
+            stderr: { on: vi.fn() },
+            stdin: { write: vi.fn(), end: vi.fn() },
+            on: vi.fn((event, callback) => {
+                if (event === 'close') callback(0);
+            }),
+        };
+        vi.mocked(spawn).mockReturnValue(mockChild as unknown as ReturnType<typeof spawn>);
+
+        const client = new GeminiCLI({});
+        const result = await client.run('gemini-3-pro-preview', 'Hello World');
+
+        expect(spawn).toHaveBeenCalledWith(
+            expect.stringContaining('gemini --yolo -p "" --model'),
+            expect.any(Object),
+        );
+        expect(result.code).toBe(0);
+        expect(result.shouldRetry).toBe(false);
+        expect(result.output).toBe('mock response');
+    });
+
+    it('should return retry status on 429 ResourceExhausted', async () => {
+        const mockChild = {
+            stdout: { on: vi.fn() },
+            stderr: {
+                on: vi.fn((event, cb) => {
+                    if (event === 'data') cb('Error: ResourceExhausted (429)');
+                }),
+            },
+            stdin: { write: vi.fn(), end: vi.fn() },
+            on: vi.fn((event, callback) => {
+                if (event === 'close') callback(1);
+            }),
+        };
+        vi.mocked(spawn).mockReturnValue(mockChild as unknown as ReturnType<typeof spawn>);
+
+        const client = new GeminiCLI({});
+        const result = await client.run('gemini-3-pro-preview', 'Hello World');
+
+        expect(result.code).toBe(1);
+        expect(result.shouldRetry).toBe(true);
+        expect(result.output).toBe('');
+    });
+
+    it('should return failure without retry on other errors', async () => {
+        const mockChild = {
+            stdout: { on: vi.fn() },
+            stderr: {
+                on: vi.fn((event, cb) => {
+                    if (event === 'data') cb('Other fatal model error');
+                }),
+            },
+            stdin: { write: vi.fn(), end: vi.fn() },
+            on: vi.fn((event, callback) => {
+                if (event === 'close') callback(2);
+            }),
+        };
+        vi.mocked(spawn).mockReturnValue(mockChild as unknown as ReturnType<typeof spawn>);
+
+        const client = new GeminiCLI({});
+        const result = await client.run('gemini-3-pro-preview', 'Hello World');
+
+        expect(result.code).toBe(2);
+        expect(result.shouldRetry).toBe(false);
+    });
+
+    it('should catch spawn errors', async () => {
+        const mockChild = {
+            stdout: { on: vi.fn() },
+            stderr: { on: vi.fn() },
+            stdin: { write: vi.fn(), end: vi.fn() },
+            on: vi.fn((event, callback) => {
+                if (event === 'error') callback(new Error('Spawn failed'));
+            }),
+        };
+        vi.mocked(spawn).mockReturnValue(mockChild as unknown as ReturnType<typeof spawn>);
+
+        const client = new GeminiCLI({});
+        const result = await client.run('gemini-3-pro-preview', 'Hello World');
+
+        expect(result.code).toBe(1);
+        expect(result.shouldRetry).toBe(false);
+        expect(result.output).toBe('');
+    });
+
+    it('should use a custom command template', async () => {
+        const mockChild = {
+            stdout: { on: vi.fn() },
+            stderr: { on: vi.fn() },
+            stdin: { write: vi.fn(), end: vi.fn() },
+            on: vi.fn((event, callback) => {
+                if (event === 'close') callback(0);
+            }),
+        };
+        vi.mocked(spawn).mockReturnValue(mockChild as unknown as ReturnType<typeof spawn>);
+
+        const client = new GeminiCLI({ commandTemplate: 'echo {model}' });
+        await client.run('gemini-3-pro-preview', 'Hello World');
+
+        expect(spawn).toHaveBeenCalledWith('echo gemini-3-pro-preview', expect.any(Object));
+    });
+});

package/tsconfig.build.json

@@ -0,0 +1,7 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": [
+        "tests/**/*",
+        "**/*.test.ts"
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "lib": [
+            "ESNext"
+        ],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "outDir": "dist",
+        "rootDir": "src"
+    },
+    "include": [
+        "src/**/*"
+    ]
+}