@nemus-cli/nemus 0.2.1

package/src/utils/repo-resolver.ts

@@ -0,0 +1,294 @@
+/**
+ * Fuzzy repository name resolver.
+ *
+ * Resolves user-supplied repo name inputs (which may be partial, mis-spelled,
+ * or differently-cased) to actual repository objects from the full list.
+ *
+ * Scoring ladder (higher = better match):
+ *  100  exact case-sensitive match
+ *   95  case-insensitive exact match
+ *   90  normalised exact match (spaces/underscores → hyphens)
+ *   80  input is a hyphen-boundary prefix of repo name  e.g. "platform" → "platform-app"
+ *   75  repo name is a hyphen-boundary prefix of input
+ *   65  input is a substring of repo name
+ *   60  repo name is a substring of input
+ *   30–50 Levenshtein edit distance ≤ threshold (typo tolerance)
+ *
+ * A match is only returned when score ≥ MIN_SCORE (30).
+ */
+
+/** Minimum score required to accept a fuzzy match. */
+const MIN_SCORE = 30;
+
+export interface FuzzyMatch<T> {
+  repo: T;
+  /** 0-100 confidence score. */
+  score: number;
+  /** True only for exact or case/normalisation-only matches (score ≥ 90). */
+  exact: boolean;
+}
+
+/**
+ * Normalise a repo name for comparison:
+ *  - lowercase
+ *  - spaces and underscores → hyphens
+ *  - collapse repeated hyphens
+ */
+function normalise(s: string): string {
+  return s
+    .trim()                          // strip leading/trailing whitespace first
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')         // spaces and underscores → hyphens
+    .replace(/-{2,}/g, '-')          // collapse repeated hyphens
+    .replace(/^-+|-+$/g, '');        // strip any leading/trailing hyphens
+}
+
+/**
+ * Compute the Levenshtein edit distance between two strings.
+ */
+export function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  // Use two alternating rows to keep memory O(n)
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array<number>(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      curr[j] =
+        a[i - 1] === b[j - 1]
+          ? prev[j - 1]
+          : 1 + Math.min(prev[j - 1], prev[j], curr[j - 1]);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+/**
+ * Damerau-Levenshtein distance (Optimal String Alignment variant).
+ *
+ * Like {@link levenshtein} but an ADJACENT TRANSPOSITION counts as a single
+ * edit — so "capser" ↔ "casper" is distance 1, not 2. Transposing two
+ * neighbouring characters is the most common human typo, so this is what we
+ * use for typo-tolerant repo matching. Names are short, so the full O(mn)
+ * matrix is negligible.
+ */
+export function damerauLevenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+
+  const d: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) d[i][0] = i;
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(
+        d[i - 1][j] + 1,        // deletion
+        d[i][j - 1] + 1,        // insertion
+        d[i - 1][j - 1] + cost, // substitution
+      );
+      // Adjacent transposition: a[i-1] a[i-2] == b[j-2] b[j-1]
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+      }
+    }
+  }
+  return d[m][n];
+}
+
+/**
+ * Score how well `originalInput` matches `originalRepo`.
+ * All normalisation is done here so the scoring ladder is fully reachable.
+ */
+function scoreMatch(originalInput: string, originalRepo: string): number {
+  // Exact (case-sensitive)
+  if (originalRepo === originalInput) return 100;
+
+  // Case-insensitive exact
+  if (originalRepo.toLowerCase() === originalInput.toLowerCase()) return 95;
+
+  // Normalised exact (spaces/underscores → hyphens; reachable for e.g. "my_app" or "my app")
+  const normInput = normalise(originalInput);
+  const normRepo = normalise(originalRepo);
+  if (normRepo === normInput) return 90;
+
+  // Prefix: normInput is a hyphen-boundary prefix of normRepo
+  // e.g. "platform" → "platform-app"
+  if (normRepo.startsWith(normInput + '-')) return 80;
+
+  // Prefix: normRepo is a hyphen-boundary prefix of normInput
+  if (normInput.startsWith(normRepo + '-')) return 75;
+
+  // Substring: normInput appears inside normRepo
+  if (normRepo.includes(normInput)) return 65;
+
+  // Substring: normRepo appears inside normInput
+  if (normInput.includes(normRepo)) return 60;
+
+  // Token-level match: split by hyphens and see how many tokens overlap
+  const inputTokens = normInput.split('-').filter(Boolean);
+  const repoTokens = normRepo.split('-').filter(Boolean);
+  if (inputTokens.length > 0 && repoTokens.length > 0) {
+    let matched = 0;
+    for (const it of inputTokens) {
+      if (repoTokens.some(rt => rt === it || rt.startsWith(it) || it.startsWith(rt))) {
+        matched++;
+      }
+    }
+    if (matched > 0) {
+      const tokenScore = Math.round(
+        (matched / Math.max(inputTokens.length, repoTokens.length)) * 55,
+      );
+      if (tokenScore >= MIN_SCORE) return tokenScore;
+    }
+  }
+
+  // Typo tolerance — Damerau-Levenshtein so an adjacent transposition
+  // (e.g. "capser" → "casper") counts as a single edit.
+  const dist = damerauLevenshtein(normInput, normRepo);
+  // Allow more edits for longer names (up to 3, never more)
+  const maxDist = Math.min(3, Math.floor(Math.max(normInput.length, normRepo.length) * 0.25));
+  if (dist <= maxDist && maxDist > 0) {
+    return Math.max(MIN_SCORE, 50 - dist * 10);
+  }
+
+  return 0;
+}
+
+/**
+ * Find the best-matching repo from `allRepos` for a given user-supplied `input`.
+ *
+ * @param input    The repo name as typed/extracted (may be partial or mis-spelled).
+ * @param allRepos Full list of available repositories (must have a `.name` string field).
+ * @returns        The best match and its score, or `null` if no match is good enough.
+ */
+export function fuzzyFindRepo<T extends { name: string }>(
+  input: string,
+  allRepos: T[],
+): FuzzyMatch<T> | null {
+  if (!input || allRepos.length === 0) return null;
+  // Inputs like "_", "-", or "   " normalise to ""; String#includes('') is
+  // always true, so they would match every repo. Reject them early.
+  if (!normalise(input)) return null;
+
+  let best: FuzzyMatch<T> | null = null;
+
+  for (const repo of allRepos) {
+    const score = scoreMatch(input, repo.name);
+    if (score > 0 && (!best || score > best.score)) {
+      best = { repo, score, exact: score >= 90 };
+    }
+  }
+
+  if (best && best.score >= MIN_SCORE) return best;
+  return null;
+}
+
+/**
+ * Resolve an array of user-supplied repo name inputs against the full repo list.
+ *
+ * Returns:
+ *  - `resolved`: array of `{ input, repo, exact }` for each successfully matched name
+ *  - `notFound`:  array of input strings that had no good match
+ */
+export function resolveRepoNames<T extends { name: string }>(
+  inputs: string[],
+  allRepos: T[],
+): { resolved: Array<{ input: string; repo: T; exact: boolean }>; notFound: string[] } {
+  const resolved: Array<{ input: string; repo: T; exact: boolean }> = [];
+  const notFound: string[] = [];
+  // Deduplicate: if two inputs fuzzy-resolve to the same repo, keep only the first.
+  const seen = new Set<string>();
+
+  for (const input of inputs) {
+    const match = fuzzyFindRepo(input, allRepos);
+    if (match) {
+      if (!seen.has(match.repo.name)) {
+        seen.add(match.repo.name);
+        resolved.push({ input, repo: match.repo, exact: match.exact });
+      }
+      // else: duplicate resolution — silently skip (first wins)
+    } else {
+      notFound.push(input);
+    }
+  }
+
+  return { resolved, notFound };
+}
+
+/** Suffix charset shared with the MCP update_workspace tool (name-suffix dir). */
+export const VALID_SUFFIX = /^[a-zA-Z0-9_-]+$/;
+
+export interface RepoSpec {
+  /** Repo name to resolve (may be fuzzy). */
+  name: string;
+  /** Optional instance suffix — clones the same repo into `<repo>-<suffix>`. */
+  suffix?: string;
+}
+
+/**
+ * Parse a single `--repos` entry that may carry an instance suffix.
+ *
+ * The same repository can be added to a workspace more than once by giving
+ * each copy a distinct suffix, e.g. a git-worktree-style second checkout:
+ *
+ *   "casper"            -> { name: "casper" }                  (dir: casper)
+ *   "casper:cas-101"    -> { name: "casper", suffix: "cas-101"} (dir: casper-cas-101)
+ *
+ * This mirrors the MCP `update_workspace` tool's `{ name, suffix }` shape so
+ * the CLI and agent paths behave identically.
+ */
+export function parseRepoSpec(spec: string): RepoSpec {
+  const trimmed = spec.trim();
+  const idx = trimmed.indexOf(':');
+  if (idx > 0) {
+    const name = trimmed.slice(0, idx).trim();
+    const suffix = trimmed.slice(idx + 1).trim();
+    return suffix ? { name, suffix } : { name };
+  }
+  return { name: trimmed };
+}
+
+/**
+ * Resolve an array of `--repos` specs (each possibly `name:suffix`) into repo
+ * entries with their target directory names. Unlike {@link resolveRepoNames},
+ * this dedupes by the final **directory name**, so the same repo can appear
+ * multiple times under different suffixes.
+ */
+export function resolveRepoSpecs<T extends { name: string }>(
+  inputs: string[],
+  allRepos: T[],
+): {
+  resolved: Array<{ input: string; repo: T; exact: boolean; suffix?: string; directoryName: string }>;
+  notFound: string[];
+  invalidSuffix: string[];
+} {
+  const resolved: Array<{ input: string; repo: T; exact: boolean; suffix?: string; directoryName: string }> = [];
+  const notFound: string[] = [];
+  const invalidSuffix: string[] = [];
+  const seenDirs = new Set<string>();
+
+  for (const input of inputs) {
+    const spec = parseRepoSpec(input);
+    if (spec.suffix !== undefined && !VALID_SUFFIX.test(spec.suffix)) {
+      invalidSuffix.push(input);
+      continue;
+    }
+    const match = fuzzyFindRepo(spec.name, allRepos);
+    if (!match) {
+      notFound.push(spec.name);
+      continue;
+    }
+    const directoryName = spec.suffix ? `${match.repo.name}-${spec.suffix}` : match.repo.name;
+    if (seenDirs.has(directoryName)) continue; // duplicate target dir within this batch
+    seenDirs.add(directoryName);
+    resolved.push({ input, repo: match.repo, exact: match.exact, suffix: spec.suffix, directoryName });
+  }
+
+  return { resolved, notFound, invalidSuffix };
+}

package/src/utils/retry.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from 'vitest';
+import { isRetryableError, withRetry } from './retry';
+
+// Mock the logger to avoid console output during tests
+vi.mock('./logger', () => ({
+  logWarning: vi.fn(),
+}));
+
+describe('isRetryableError', () => {
+  it('returns true for timeout errors', () => {
+    expect(isRetryableError(new Error('Operation timeout'))).toBe(true);
+  });
+
+  it('returns true for ETIMEDOUT errors', () => {
+    expect(isRetryableError(new Error('connect ETIMEDOUT 1.2.3.4:443'))).toBe(true);
+  });
+
+  it('returns true for ECONNREFUSED errors', () => {
+    expect(isRetryableError(new Error('connect ECONNREFUSED 127.0.0.1:22'))).toBe(true);
+  });
+
+  it('returns true for ECONNRESET errors', () => {
+    expect(isRetryableError(new Error('read ECONNRESET'))).toBe(true);
+  });
+
+  it('returns true for ENOTFOUND errors', () => {
+    expect(isRetryableError(new Error('getaddrinfo ENOTFOUND github.com'))).toBe(true);
+  });
+
+  it('returns false for authentication failed', () => {
+    expect(isRetryableError(new Error('Authentication failed for repo'))).toBe(false);
+  });
+
+  it('returns false for permission denied', () => {
+    expect(isRetryableError(new Error('Permission denied (publickey)'))).toBe(false);
+  });
+
+  it('returns false for 404 errors', () => {
+    expect(isRetryableError(new Error('Repository not found: 404'))).toBe(false);
+  });
+
+  it('returns false for 401 errors', () => {
+    expect(isRetryableError(new Error('HTTP 401 Unauthorized'))).toBe(false);
+  });
+
+  it('returns false for 403 errors', () => {
+    expect(isRetryableError(new Error('HTTP 403 Forbidden'))).toBe(false);
+  });
+
+  it('returns false for repository not found', () => {
+    expect(isRetryableError(new Error('repository not found'))).toBe(false);
+  });
+
+  it('returns false for generic errors', () => {
+    expect(isRetryableError(new Error('Something went wrong'))).toBe(false);
+  });
+});
+
+describe('withRetry', () => {
+  it('succeeds on first try', async () => {
+    const fn = vi.fn().mockResolvedValue('success');
+    const result = await withRetry(fn);
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('succeeds on retry after retryable failure', async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error('connect ETIMEDOUT'))
+      .mockResolvedValueOnce('success');
+
+    const result = await withRetry(fn, { maxRetries: 1, initialDelayMs: 10 });
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('fails after max retries exhausted', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('connect ETIMEDOUT'));
+
+    await expect(
+      withRetry(fn, { maxRetries: 2, initialDelayMs: 10 })
+    ).rejects.toThrow('connect ETIMEDOUT');
+    expect(fn).toHaveBeenCalledTimes(3); // initial + 2 retries
+  });
+
+  it('does not retry non-retryable errors', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('Authentication failed'));
+
+    await expect(
+      withRetry(fn, { maxRetries: 3, initialDelayMs: 10 })
+    ).rejects.toThrow('Authentication failed');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('applies exponential backoff', async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error('ECONNRESET'))
+      .mockRejectedValueOnce(new Error('ECONNRESET'))
+      .mockResolvedValueOnce('success');
+
+    const start = Date.now();
+    await withRetry(fn, { maxRetries: 2, initialDelayMs: 50, backoffMultiplier: 2, maxDelayMs: 10000 });
+    const elapsed = Date.now() - start;
+
+    // Should have waited ~50ms + ~100ms = ~150ms (with some tolerance)
+    expect(elapsed).toBeGreaterThanOrEqual(100);
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it('respects maxDelayMs', async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error('ECONNRESET'))
+      .mockRejectedValueOnce(new Error('ECONNRESET'))
+      .mockResolvedValueOnce('success');
+
+    const start = Date.now();
+    await withRetry(fn, { maxRetries: 2, initialDelayMs: 100, backoffMultiplier: 100, maxDelayMs: 150 });
+    const elapsed = Date.now() - start;
+
+    // First delay 100ms, second should be capped at 150ms (not 100*100=10000)
+    expect(elapsed).toBeLessThan(500);
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+});

package/src/utils/retry.ts

@@ -0,0 +1,85 @@
+import { logWarning } from './logger';
+
+export interface RetryOptions {
+  maxRetries: number;
+  initialDelayMs: number;
+  backoffMultiplier: number;
+  maxDelayMs: number;
+}
+
+const DEFAULT_OPTIONS: RetryOptions = {
+  maxRetries: 1,
+  initialDelayMs: 2000,
+  backoffMultiplier: 2,
+  maxDelayMs: 10000,
+};
+
+const NON_RETRYABLE_PATTERNS = [
+  'authentication failed',
+  'permission denied',
+  'repository not found',
+  'could not read from remote repository',
+  '401',
+  '403',
+  '404',
+];
+
+const RETRYABLE_PATTERNS = [
+  'timeout',
+  'etimedout',
+  'econnrefused',
+  'econnreset',
+  'enotfound',
+];
+
+export function isRetryableError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+
+  for (const pattern of NON_RETRYABLE_PATTERNS) {
+    if (message.includes(pattern)) {
+      return false;
+    }
+  }
+
+  for (const pattern of RETRYABLE_PATTERNS) {
+    if (message.includes(pattern)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  options?: Partial<RetryOptions>,
+  operationName?: string
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: unknown;
+  let delay = opts.initialDelayMs;
+
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt >= opts.maxRetries || !isRetryableError(error)) {
+        throw error;
+      }
+
+      const name = operationName || 'operation';
+      logWarning(`${name} failed (attempt ${attempt + 1}/${opts.maxRetries + 1}), retrying in ${(delay / 1000).toFixed(1)}s...`);
+
+      await sleep(delay);
+      delay = Math.min(delay * opts.backoffMultiplier, opts.maxDelayMs);
+    }
+  }
+
+  throw lastError;
+}

package/src/utils/run-operations.ts

@@ -0,0 +1,38 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+const COMMAND_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+
+export interface RunResult {
+  repo: string;
+  status: 'success' | 'failed';
+  stdout: string;
+  stderr: string;
+  error?: string;
+}
+
+export async function runInRepo(repoPath: string, repoName: string, command: string): Promise<RunResult> {
+  try {
+    const { stdout, stderr } = await execAsync(command, {
+      cwd: repoPath,
+      timeout: COMMAND_TIMEOUT,
+    });
+
+    return {
+      repo: repoName,
+      status: 'success',
+      stdout: stdout.trim(),
+      stderr: stderr.trim(),
+    };
+  } catch (error: any) {
+    return {
+      repo: repoName,
+      status: 'failed',
+      stdout: error.stdout?.trim() || '',
+      stderr: error.stderr?.trim() || '',
+      error: error.message,
+    };
+  }
+}