@mrpatronz/nexusflow 0.2.13 → 0.2.17

package/src/utils/git.ts

@@ -1,61 +1,117 @@
-/**
- * @module utils/git
- * Low-level git helper functions used throughout NexusFlow.
- */
-
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { execa } from 'execa';
-
-/**
- * Checks whether the given directory is a git repository
- * by testing for the presence of a `.git` entry.
- *
- * @param dirPath - Absolute path to the directory.
- * @returns `true` if a `.git` file or directory exists.
- */
-export async function isGitRepo(dirPath: string): Promise<boolean> {
-  try {
-    const gitPath = path.join(dirPath, '.git');
-    await fs.access(gitPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Runs `git fetch origin` inside the given repository.
- *
- * @param repoPath - Absolute path to the repo root.
- */
-export async function gitFetch(repoPath: string): Promise<void> {
-  await execa('git', ['fetch', 'origin'], { cwd: repoPath });
-}
-
-/**
- * Detects the default branch of a repository by inspecting remote branches.
- * Prefers `main` over `master`. Falls back to `'main'` when neither is found.
- *
- * @param repoPath - Absolute path to the repo root.
- * @returns The name of the default branch.
- */
-export async function detectDefaultBranch(repoPath: string): Promise<string> {
-  try {
-    const { stdout } = await execa('git', ['branch', '-r'], { cwd: repoPath });
-    const branches = stdout.split('\n').map((b) => b.trim());
-
-    if (branches.some((b) => b === 'origin/main' || b.endsWith('/origin/main'))) {
-      return 'main';
-    }
-
-    if (branches.some((b) => b === 'origin/master' || b.endsWith('/origin/master'))) {
-      return 'master';
-    }
-
-    // Fallback — assume main.
-    return 'main';
-  } catch {
-    return 'main';
-  }
-}
+/**
+ * @module utils/git
+ * Low-level git helper functions used throughout NexusFlow.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execa } from 'execa';
+
+/**
+ * Checks whether the given directory is a git repository
+ * by testing for the presence of a `.git` entry.
+ *
+ * @param dirPath - Absolute path to the directory.
+ * @returns `true` if a `.git` file or directory exists.
+ */
+export async function isGitRepo(dirPath: string): Promise<boolean> {
+  try {
+    const gitPath = path.join(dirPath, '.git');
+    await fs.access(gitPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Runs `git fetch origin` inside the given repository.
+ *
+ * @param repoPath - Absolute path to the repo root.
+ */
+export async function gitFetch(repoPath: string): Promise<void> {
+  await execa('git', ['fetch', 'origin'], { cwd: repoPath });
+}
+
+/**
+ * Detects the default branch of a repository by inspecting remote branches.
+ * Prefers `main` over `master`. Falls back to `'main'` when neither is found.
+ *
+ * @param repoPath - Absolute path to the repo root.
+ * @returns The name of the default branch.
+ */
+export async function detectDefaultBranch(repoPath: string): Promise<string> {
+  try {
+    const { stdout } = await execa('git', ['branch', '-r'], { cwd: repoPath });
+    const branches = stdout.split('\n').map((b) => b.trim());
+
+    if (branches.some((b) => b === 'origin/main' || b.endsWith('/origin/main'))) {
+      return 'main';
+    }
+
+    if (branches.some((b) => b === 'origin/master' || b.endsWith('/origin/master'))) {
+      return 'master';
+    }
+
+    // Fallback — assume main.
+    return 'main';
+  } catch {
+    return 'main';
+  }
+}
+
+/**
+ * Checks if the given branch name matches Git branch conventions (based on git-check-ref-format):
+ * - No spaces, backslashes, or control characters.
+ * - At least 1 character long.
+ * - Is not exactly '@'.
+ * - Does not start with a dash.
+ * - Does not start or end with a forward slash.
+ * - Does not contain consecutive dots, consecutive slashes, or '@{'.
+ * - Does not end with '.'.
+ * - Does not contain forbidden characters: ~, ^, :, ?, *, [
+ * - No component starts with a dot, ends with '.lock', or is exactly 'HEAD'.
+ *
+ * @param name - The branch name to validate.
+ * @returns `true` if the branch name is valid.
+ */
+export function isValidBranchName(name: string): boolean {
+  if (!name || name.length === 0) {
+    return false;
+  }
+  if (name === '@') {
+    return false;
+  }
+  if (name.startsWith('-')) {
+    return false;
+  }
+  const forbiddenCharsOrSpaces = /[\x00-\x20\x7F~^:?*[\\]/;
+  if (forbiddenCharsOrSpaces.test(name)) {
+    return false;
+  }
+  if (name.includes('..') || name.includes('@{') || name.includes('//')) {
+    return false;
+  }
+  if (name.startsWith('/') || name.endsWith('/')) {
+    return false;
+  }
+  if (name.endsWith('.')) {
+    return false;
+  }
+  
+  const components = name.split('/');
+  for (const component of components) {
+    if (component.startsWith('.')) {
+      return false;
+    }
+    if (component.endsWith('.lock')) {
+      return false;
+    }
+    if (component === 'HEAD') {
+      return false;
+    }
+  }
+
+  return true;
+}
+

package/src/utils/local-ai.test.ts

@@ -1,130 +1,130 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { callLocalLlm, isOllamaModelAvailable, getOpenAiCompatibleUrl } from './local-ai.js';
-
-describe('local-ai utilities', () => {
-  beforeEach(() => {
-    vi.stubGlobal('fetch', vi.fn());
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  describe('isOllamaModelAvailable', () => {
-    it('should match exact model names and tag variations', () => {
-      const models = [{ name: 'qwen2.5-coder:1.5b' }, { name: 'llama3:latest' }];
-      expect(isOllamaModelAvailable(models, 'qwen2.5-coder:1.5b')).toBe(true);
-      expect(isOllamaModelAvailable(models, 'llama3')).toBe(true);
-      expect(isOllamaModelAvailable(models, 'llama3:latest')).toBe(true);
-      expect(isOllamaModelAvailable(models, 'non-existent')).toBe(false);
-    });
-  });
-
-  describe('getOpenAiCompatibleUrl', () => {
-    it('should properly format endpoint URLs', () => {
-      expect(getOpenAiCompatibleUrl('http://localhost:11434', '/v1/chat/completions')).toBe('http://localhost:11434/v1/chat/completions');
-      expect(getOpenAiCompatibleUrl('http://localhost:11434/', '/v1/chat/completions')).toBe('http://localhost:11434/v1/chat/completions');
-      expect(getOpenAiCompatibleUrl('http://localhost:1234/v1', '/v1/chat/completions')).toBe('http://localhost:1234/v1/chat/completions');
-      expect(getOpenAiCompatibleUrl('http://localhost:1234/v1/', '/v1/chat/completions')).toBe('http://localhost:1234/v1/chat/completions');
-    });
-  });
-
-  describe('callLocalLlm', () => {
-    const configOllama = {
-      enabled: true,
-      provider: 'ollama' as const,
-      endpoint: 'http://localhost:11434',
-      model: 'qwen2.5-coder:1.5b',
-    };
-
-    const configOpenAi = {
-      enabled: true,
-      provider: 'openai-compatible' as const,
-      endpoint: 'http://localhost:1234/v1',
-      model: 'custom-model',
-    };
-
-    const messages = [{ role: 'user' as const, content: 'Hello' }];
-
-    it('should request and return message content for Ollama provider', async () => {
-      const mockResponse = {
-        message: {
-          content: 'Hello from Ollama!',
-        },
-      };
-
-      vi.mocked(fetch).mockResolvedValue({
-        ok: true,
-        json: () => Promise.resolve(mockResponse),
-      } as any);
-
-      const response = await callLocalLlm(configOllama, messages);
-
-      expect(response).toBe('Hello from Ollama!');
-      expect(fetch).toHaveBeenCalledWith('http://localhost:11434/api/chat', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          model: 'qwen2.5-coder:1.5b',
-          messages,
-          stream: false,
-        }),
-        signal: expect.any(AbortSignal),
-      });
-    });
-
-    it('should throw an error if Ollama response is not ok', async () => {
-      vi.mocked(fetch).mockResolvedValue({
-        ok: false,
-        status: 500,
-        text: () => Promise.resolve('Internal server error'),
-      } as any);
-
-      await expect(callLocalLlm(configOllama, messages)).rejects.toThrow(
-        'Ollama request failed with status 500: Internal server error'
-      );
-    });
-
-    it('should request and return message content for OpenAI provider', async () => {
-      const mockResponse = {
-        choices: [
-          {
-            message: {
-              content: 'Hello from OpenAI!',
-            },
-          },
-        ],
-      };
-
-      vi.mocked(fetch).mockResolvedValue({
-        ok: true,
-        json: () => Promise.resolve(mockResponse),
-      } as any);
-
-      const response = await callLocalLlm(configOpenAi, messages);
-
-      expect(response).toBe('Hello from OpenAI!');
-      expect(fetch).toHaveBeenCalledWith('http://localhost:1234/v1/chat/completions', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          model: 'custom-model',
-          messages,
-          stream: false,
-        }),
-        signal: expect.any(AbortSignal),
-      });
-    });
-
-    it('should throw an error if OpenAI response has invalid format', async () => {
-      vi.mocked(fetch).mockResolvedValue({
-        ok: true,
-        json: () => Promise.resolve({}),
-      } as any);
-
-      await expect(callLocalLlm(configOpenAi, messages)).rejects.toThrow(
-        'Invalid response format received from OpenAI-compatible endpoint'
-      );
-    });
-  });
-});
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { callLocalLlm, isOllamaModelAvailable, getOpenAiCompatibleUrl } from './local-ai.js';
+
+describe('local-ai utilities', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', vi.fn());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('isOllamaModelAvailable', () => {
+    it('should match exact model names and tag variations', () => {
+      const models = [{ name: 'qwen2.5-coder:1.5b' }, { name: 'llama3:latest' }];
+      expect(isOllamaModelAvailable(models, 'qwen2.5-coder:1.5b')).toBe(true);
+      expect(isOllamaModelAvailable(models, 'llama3')).toBe(true);
+      expect(isOllamaModelAvailable(models, 'llama3:latest')).toBe(true);
+      expect(isOllamaModelAvailable(models, 'non-existent')).toBe(false);
+    });
+  });
+
+  describe('getOpenAiCompatibleUrl', () => {
+    it('should properly format endpoint URLs', () => {
+      expect(getOpenAiCompatibleUrl('http://localhost:11434', '/v1/chat/completions')).toBe('http://localhost:11434/v1/chat/completions');
+      expect(getOpenAiCompatibleUrl('http://localhost:11434/', '/v1/chat/completions')).toBe('http://localhost:11434/v1/chat/completions');
+      expect(getOpenAiCompatibleUrl('http://localhost:1234/v1', '/v1/chat/completions')).toBe('http://localhost:1234/v1/chat/completions');
+      expect(getOpenAiCompatibleUrl('http://localhost:1234/v1/', '/v1/chat/completions')).toBe('http://localhost:1234/v1/chat/completions');
+    });
+  });
+
+  describe('callLocalLlm', () => {
+    const configOllama = {
+      enabled: true,
+      provider: 'ollama' as const,
+      endpoint: 'http://localhost:11434',
+      model: 'qwen2.5-coder:1.5b',
+    };
+
+    const configOpenAi = {
+      enabled: true,
+      provider: 'openai-compatible' as const,
+      endpoint: 'http://localhost:1234/v1',
+      model: 'custom-model',
+    };
+
+    const messages = [{ role: 'user' as const, content: 'Hello' }];
+
+    it('should request and return message content for Ollama provider', async () => {
+      const mockResponse = {
+        message: {
+          content: 'Hello from Ollama!',
+        },
+      };
+
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockResponse),
+      } as any);
+
+      const response = await callLocalLlm(configOllama, messages);
+
+      expect(response).toBe('Hello from Ollama!');
+      expect(fetch).toHaveBeenCalledWith('http://localhost:11434/api/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          model: 'qwen2.5-coder:1.5b',
+          messages,
+          stream: false,
+        }),
+        signal: expect.any(AbortSignal),
+      });
+    });
+
+    it('should throw an error if Ollama response is not ok', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: false,
+        status: 500,
+        text: () => Promise.resolve('Internal server error'),
+      } as any);
+
+      await expect(callLocalLlm(configOllama, messages)).rejects.toThrow(
+        'Ollama request failed with status 500: Internal server error'
+      );
+    });
+
+    it('should request and return message content for OpenAI provider', async () => {
+      const mockResponse = {
+        choices: [
+          {
+            message: {
+              content: 'Hello from OpenAI!',
+            },
+          },
+        ],
+      };
+
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockResponse),
+      } as any);
+
+      const response = await callLocalLlm(configOpenAi, messages);
+
+      expect(response).toBe('Hello from OpenAI!');
+      expect(fetch).toHaveBeenCalledWith('http://localhost:1234/v1/chat/completions', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          model: 'custom-model',
+          messages,
+          stream: false,
+        }),
+        signal: expect.any(AbortSignal),
+      });
+    });
+
+    it('should throw an error if OpenAI response has invalid format', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({}),
+      } as any);
+
+      await expect(callLocalLlm(configOpenAi, messages)).rejects.toThrow(
+        'Invalid response format received from OpenAI-compatible endpoint'
+      );
+    });
+  });
+});

package/src/utils/local-ai.ts

@@ -1,111 +1,111 @@
-/**
- * @module utils/local-ai
- * Handles requests to local LLM servers (Ollama or OpenAI-compatible like LM Studio).
- */
-
-import type { LocalLlmConfig } from '../types.js';
-
-export interface LocalLlmMessage {
-  role: 'system' | 'user' | 'assistant';
-  content: string;
-}
-
-/**
- * Sends a chat completion request to the configured local LLM provider.
- * Supports Ollama-specific API and standard OpenAI-compatible endpoints.
- */
-export async function callLocalLlm(
-  config: LocalLlmConfig,
-  messages: LocalLlmMessage[],
-): Promise<string> {
-  const { provider, endpoint, model } = config;
-  const cleanEndpoint = endpoint.replace(/\/$/, '');
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 60_000);
-
-  try {
-    if (provider === 'ollama') {
-      const url = `${cleanEndpoint}/api/chat`;
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-          model,
-          messages,
-          stream: false,
-        }),
-        signal: controller.signal,
-      });
-
-      if (!response.ok) {
-        const text = await response.text();
-        throw new Error(`Ollama request failed with status ${response.status}: ${text}`);
-      }
-
-      const data: any = await response.json();
-      if (data?.message?.content) {
-        return data.message.content;
-      }
-      throw new Error('Invalid response format received from Ollama');
-    } else {
-      // OpenAI-compatible provider
-      const url = getOpenAiCompatibleUrl(cleanEndpoint, '/v1/chat/completions');
-
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-          model,
-          messages,
-          stream: false,
-        }),
-        signal: controller.signal,
-      });
-
-      if (!response.ok) {
-        const text = await response.text();
-        throw new Error(`OpenAI-compatible request failed with status ${response.status}: ${text}`);
-      }
-
-      const data: any = await response.json();
-      if (data?.choices?.[0]?.message?.content) {
-        return data.choices[0].message.content;
-      }
-      throw new Error('Invalid response format received from OpenAI-compatible endpoint');
-    }
-  } catch (error: any) {
-    if (error.name === 'AbortError') {
-      throw new Error('Local LLM request timed out after 60 seconds');
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-/**
- * Checks whether a target model name matches any model in an Ollama model list.
- * Handles tag variations like 'model' vs 'model:latest' vs 'model:7b'.
- */
-export function isOllamaModelAvailable(models: { name: string }[], targetModel: string): boolean {
-  const normalize = (name: string) => name.includes(':') ? name : `${name}:latest`;
-  const targetNorm = normalize(targetModel);
-  return models.some((m) => normalize(m.name) === targetNorm);
-}
-
-/**
- * Helper to build standard OpenAI compatible URLs.
- * Handles cases where the configured endpoint already has or does not have `/v1`.
- */
-export function getOpenAiCompatibleUrl(endpoint: string, suffix: string): string {
-  const cleanEndpoint = endpoint.replace(/\/$/, '');
-  const hasV1 = /\/v1\/?$/.test(cleanEndpoint);
-  if (hasV1) {
-    return `${cleanEndpoint.replace(/\/v1\/?$/, '')}${suffix}`;
-  }
-  return `${cleanEndpoint}${suffix}`;
-}
+/**
+ * @module utils/local-ai
+ * Handles requests to local LLM servers (Ollama or OpenAI-compatible like LM Studio).
+ */
+
+import type { LocalLlmConfig } from '../types.js';
+
+export interface LocalLlmMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Sends a chat completion request to the configured local LLM provider.
+ * Supports Ollama-specific API and standard OpenAI-compatible endpoints.
+ */
+export async function callLocalLlm(
+  config: LocalLlmConfig,
+  messages: LocalLlmMessage[],
+): Promise<string> {
+  const { provider, endpoint, model } = config;
+  const cleanEndpoint = endpoint.replace(/\/$/, '');
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 60_000);
+
+  try {
+    if (provider === 'ollama') {
+      const url = `${cleanEndpoint}/api/chat`;
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model,
+          messages,
+          stream: false,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Ollama request failed with status ${response.status}: ${text}`);
+      }
+
+      const data: any = await response.json();
+      if (data?.message?.content) {
+        return data.message.content;
+      }
+      throw new Error('Invalid response format received from Ollama');
+    } else {
+      // OpenAI-compatible provider
+      const url = getOpenAiCompatibleUrl(cleanEndpoint, '/v1/chat/completions');
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model,
+          messages,
+          stream: false,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`OpenAI-compatible request failed with status ${response.status}: ${text}`);
+      }
+
+      const data: any = await response.json();
+      if (data?.choices?.[0]?.message?.content) {
+        return data.choices[0].message.content;
+      }
+      throw new Error('Invalid response format received from OpenAI-compatible endpoint');
+    }
+  } catch (error: any) {
+    if (error.name === 'AbortError') {
+      throw new Error('Local LLM request timed out after 60 seconds');
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Checks whether a target model name matches any model in an Ollama model list.
+ * Handles tag variations like 'model' vs 'model:latest' vs 'model:7b'.
+ */
+export function isOllamaModelAvailable(models: { name: string }[], targetModel: string): boolean {
+  const normalize = (name: string) => name.includes(':') ? name : `${name}:latest`;
+  const targetNorm = normalize(targetModel);
+  return models.some((m) => normalize(m.name) === targetNorm);
+}
+
+/**
+ * Helper to build standard OpenAI compatible URLs.
+ * Handles cases where the configured endpoint already has or does not have `/v1`.
+ */
+export function getOpenAiCompatibleUrl(endpoint: string, suffix: string): string {
+  const cleanEndpoint = endpoint.replace(/\/$/, '');
+  const hasV1 = /\/v1\/?$/.test(cleanEndpoint);
+  if (hasV1) {
+    return `${cleanEndpoint.replace(/\/v1\/?$/, '')}${suffix}`;
+  }
+  return `${cleanEndpoint}${suffix}`;
+}