@nemus-cli/nemus 0.2.1

package/src/utils/validation.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { validateWorkspaceName, sanitizeWorkspaceName, checkWorkspaceExists, safeWorkspacePath, assertSafeWorkspaceName, isSafePathSegment } from './validation';
+import { WORKSPACES_DIR } from './config';
+
+describe('validateWorkspaceName', () => {
+  it('returns true for valid names', () => {
+    expect(validateWorkspaceName('my-workspace')).toBe(true);
+    expect(validateWorkspaceName('test_workspace')).toBe(true);
+    expect(validateWorkspaceName('workspace123')).toBe(true);
+    expect(validateWorkspaceName('My-Workspace_01')).toBe(true);
+  });
+
+  it('rejects empty names', () => {
+    expect(validateWorkspaceName('')).toBe('Workspace name cannot be empty');
+    expect(validateWorkspaceName('   ')).toBe('Workspace name cannot be empty');
+  });
+
+  it('rejects names with invalid characters', () => {
+    const result = validateWorkspaceName('my workspace');
+    expect(result).toContain('alphanumeric');
+
+    expect(validateWorkspaceName('my@workspace')).toContain('alphanumeric');
+    expect(validateWorkspaceName('my/workspace')).toContain('alphanumeric');
+    expect(validateWorkspaceName('my.workspace')).toContain('alphanumeric');
+  });
+
+  it('rejects names that are too short', () => {
+    const result = validateWorkspaceName('ab');
+    expect(result).toContain('at least 3');
+  });
+
+  it('rejects names that are too long', () => {
+    const longName = 'a'.repeat(51);
+    const result = validateWorkspaceName(longName);
+    expect(result).toContain('less than 50');
+  });
+});
+
+describe('sanitizeWorkspaceName', () => {
+  it('trims whitespace', () => {
+    expect(sanitizeWorkspaceName('  my-workspace  ')).toBe('my-workspace');
+  });
+
+  it('converts to lowercase', () => {
+    expect(sanitizeWorkspaceName('My-Workspace')).toBe('my-workspace');
+  });
+
+  it('trims and lowercases together', () => {
+    expect(sanitizeWorkspaceName('  MY-WORKSPACE  ')).toBe('my-workspace');
+  });
+
+  it('converts spaces to hyphens', () => {
+    expect(sanitizeWorkspaceName('my workspace')).toBe('my-workspace');
+    expect(sanitizeWorkspaceName('my  workspace')).toBe('my-workspace');
+    expect(sanitizeWorkspaceName('  My Workspace Name  ')).toBe('my-workspace-name');
+  });
+});
+
+describe('checkWorkspaceExists', () => {
+  let tempDir: string;
+  const originalEnv = process.env.WORKSPACE_MANAGER_DIR;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-test-'));
+    process.env.WORKSPACE_MANAGER_DIR = tempDir;
+  });
+
+  afterEach(async () => {
+    process.env.WORKSPACE_MANAGER_DIR = originalEnv;
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns true when workspace directory exists', async () => {
+    await fs.mkdir(path.join(tempDir, 'existing-workspace'));
+    // checkWorkspaceExists uses WORKSPACES_DIR which is evaluated at import time,
+    // so we test the path logic directly
+    const workspacePath = path.join(tempDir, 'existing-workspace');
+    try {
+      await fs.access(workspacePath);
+      expect(true).toBe(true);
+    } catch {
+      expect.fail('Directory should exist');
+    }
+  });
+
+  it('returns false when workspace directory does not exist', async () => {
+    const workspacePath = path.join(tempDir, 'non-existent');
+    try {
+      await fs.access(workspacePath);
+      expect.fail('Directory should not exist');
+    } catch {
+      expect(true).toBe(true);
+    }
+  });
+});
+
+describe('safeWorkspacePath (path-traversal guard)', () => {
+  const base = path.resolve(WORKSPACES_DIR);
+
+  it('accepts normal workspace names and keeps them inside WORKSPACES_DIR', () => {
+    for (const name of ['payments', 'my-workspace', 'ws_2', 'ABC-123']) {
+      const p = safeWorkspacePath(name);
+      expect(p).toBe(path.join(base, name));
+      expect(p.startsWith(base + path.sep)).toBe(true);
+    }
+  });
+
+  it('rejects path traversal and separators', () => {
+    for (const evil of [
+      '../etc',
+      '../../etc/passwd',
+      '..',
+      '.',
+      'foo/bar',
+      'foo\\bar',
+      '/etc/passwd',
+      '~/secrets',
+      'a/../../b',
+      'foo.bar',        // dots are not allowed in workspace names
+      '',
+    ]) {
+      expect(() => safeWorkspacePath(evil)).toThrow();
+      expect(isSafePathSegment(evil)).toBe(false);
+    }
+  });
+
+  it('rejects a NUL byte and overly long names', () => {
+    expect(() => safeWorkspacePath('foo\0bar')).toThrow();
+    expect(() => safeWorkspacePath('a'.repeat(65))).toThrow();
+  });
+
+  it('assertSafeWorkspaceName throws on non-string input', () => {
+    expect(() => assertSafeWorkspaceName(undefined as any)).toThrow();
+    expect(() => assertSafeWorkspaceName(123 as any)).toThrow();
+  });
+});

package/src/utils/validation.ts

@@ -0,0 +1,128 @@
+import * as fs from 'fs/promises';
+import { WORKSPACES_DIR } from './config';
+import * as path from 'path';
+
+const WORKSPACE_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Allowlist for a single, safe path segment used as a workspace (or suite) name.
+ * Alphanumerics plus hyphen/underscore only — it cannot express a path
+ * separator, a Windows drive, a leading `~`, or a `.`/`..` traversal component,
+ * so a value that matches this can never escape its parent directory.
+ */
+export const isSafePathSegment = (name: unknown): name is string =>
+  typeof name === 'string' && name.length > 0 && name.length <= 64 && WORKSPACE_NAME_REGEX.test(name);
+
+/**
+ * Throw unless `name` is a safe workspace-name path segment. Use this in any
+ * handler that receives a workspace/suite name from an untrusted caller (e.g.
+ * the MCP server, whose Zod schemas otherwise accept any string) BEFORE the
+ * name is used to build a filesystem path.
+ */
+export const assertSafeWorkspaceName = (name: unknown, label = 'workspace name'): void => {
+  if (!isSafePathSegment(name)) {
+    throw new Error(
+      `Invalid ${label} "${String(name)}": only letters, numbers, hyphens, and underscores are allowed ` +
+      `(no path separators, "..", or other special characters).`,
+    );
+  }
+};
+
+/**
+ * Validate a workspace name and resolve it to an absolute path guaranteed to sit
+ * directly inside WORKSPACES_DIR. This is the single choke point every code path
+ * (especially the MCP handlers) must use instead of a raw
+ * `path.join(WORKSPACES_DIR, name)` — it closes the path-traversal vector where
+ * a caller could pass e.g. "../../etc" as a workspace name to read, write,
+ * delete, or run commands outside the workspaces sandbox.
+ *
+ * Two independent guards: the allowlist above (which cannot express traversal)
+ * and a resolved-path containment check (belt-and-suspenders, also catches any
+ * future change that loosens the allowlist).
+ */
+export const safeWorkspacePath = (name: string): string => {
+  assertSafeWorkspaceName(name);
+  const base = path.resolve(WORKSPACES_DIR);
+  const resolved = path.resolve(base, name);
+  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+    throw new Error(`Refusing to use a workspace path outside the workspaces directory: "${name}"`);
+  }
+  return resolved;
+};
+
+export const validateWorkspaceName = (name: string): boolean | string => {
+  if (!name || name.trim().length === 0) {
+    return 'Workspace name cannot be empty';
+  }
+
+  if (!WORKSPACE_NAME_REGEX.test(name)) {
+    return 'Workspace name must contain only alphanumeric characters, hyphens, and underscores (spaces are automatically converted to hyphens)';
+  }
+
+  if (name.length < 3) {
+    return 'Workspace name must be at least 3 characters long';
+  }
+
+  if (name.length > 50) {
+    return 'Workspace name must be less than 50 characters';
+  }
+
+  return true;
+};
+
+export const checkWorkspaceExists = async (name: string): Promise<boolean> => {
+  const workspacePath = path.join(WORKSPACES_DIR, name);
+  try {
+    await fs.access(workspacePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const sanitizeWorkspaceName = (name: string): string => {
+  return name.trim().toLowerCase().replace(/ +/g, '-');
+};
+
+/**
+ * Resolves a workspace name conflict by generating a unique alternative name.
+ *
+ * Strategy:
+ *   1. Try appending each provided candidate suffix (e.g. repo names): `<name>-<candidate>`
+ *   2. Fall back to numeric suffixes: `<name>-2`, `<name>-3`, …
+ *
+ * @param baseName   - The sanitized workspace name that already exists.
+ * @param candidates - Optional list of preferred suffixes to try first (e.g. selected repo names).
+ * @returns A workspace name that does not yet exist on disk and passes validation.
+ */
+export const resolveWorkspaceNameConflict = async (
+  baseName: string,
+  candidates: string[] = []
+): Promise<string> => {
+  // 1. Try candidate-based suffixes (e.g. repo names)
+  for (const candidate of candidates) {
+    const suffix = sanitizeWorkspaceName(candidate)
+      .replace(/[^a-z0-9_-]/g, '-')  // extra safety — strip any bad chars after sanitise
+      .replace(/-+/g, '-')            // collapse consecutive hyphens
+      .replace(/^-|-$/g, '');         // trim leading/trailing hyphens
+
+    if (!suffix) continue;
+
+    const attempt = `${baseName}-${suffix}`;
+    if (validateWorkspaceName(attempt) !== true) continue;
+
+    const exists = await checkWorkspaceExists(attempt);
+    if (!exists) return attempt;
+  }
+
+  // 2. Fall back to numeric suffixes
+  for (let i = 2; i <= 99; i++) {
+    const attempt = `${baseName}-${i}`;
+    if (validateWorkspaceName(attempt) !== true) continue;
+
+    const exists = await checkWorkspaceExists(attempt);
+    if (!exists) return attempt;
+  }
+
+  throw new Error(`Could not resolve workspace name conflict for "${baseName}" — all attempted names already exist.`);
+};

package/src/utils/version-check.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock fs/promises
+vi.mock('fs/promises', () => ({
+  readFile: vi.fn(),
+  writeFile: vi.fn().mockResolvedValue(undefined),
+  mkdir: vi.fn().mockResolvedValue(undefined),
+}));
+
+// Mock child_process
+const mockExecFile = vi.fn();
+vi.mock('child_process', () => ({
+  execFile: (...args: unknown[]) => {
+    const callback = args[args.length - 1] as (err: Error | null, result: { stdout: string; stderr: string }) => void;
+    mockExecFile(args[0], args[1], args[2])
+      .then((result: { stdout: string; stderr: string }) => callback(null, result))
+      .catch((err: Error) => callback(err, { stdout: '', stderr: '' }));
+  },
+}));
+
+// Mock config
+vi.mock('./config', () => ({
+  CACHE_DIR: '/tmp/test-cache',
+  getPackageVersion: () => '2.20.0',
+}));
+
+import { checkForUpdate } from './version-check';
+import * as fs from 'fs/promises';
+
+describe('checkForUpdate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns null when current version matches latest', async () => {
+    // No cached check
+    vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));
+    // npm returns same version
+    mockExecFile.mockResolvedValueOnce({ stdout: '2.20.0\n', stderr: '' });
+
+    const result = await checkForUpdate();
+    expect(result).toBeNull();
+  });
+
+  it('returns update message when newer version is available', async () => {
+    vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));
+    mockExecFile.mockResolvedValueOnce({ stdout: '2.21.0\n', stderr: '' });
+
+    const result = await checkForUpdate();
+    expect(result).toContain('Update available');
+    expect(result).toContain('2.20.0');
+    expect(result).toContain('2.21.0');
+  });
+
+  it('returns null when npm check fails', async () => {
+    vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));
+    mockExecFile.mockRejectedValueOnce(new Error('npm timeout'));
+
+    const result = await checkForUpdate();
+    expect(result).toBeNull();
+  });
+
+  it('uses cached result when within 24h', async () => {
+    const recentCheck = JSON.stringify({
+      checkedAt: new Date().toISOString(),
+      latestVersion: '3.0.0',
+    });
+    vi.mocked(fs.readFile).mockResolvedValueOnce(recentCheck);
+
+    const result = await checkForUpdate();
+    expect(result).toContain('Update available');
+    // Should NOT have called npm
+    expect(mockExecFile).not.toHaveBeenCalled();
+  });
+
+  it('returns null from cache when version is current', async () => {
+    const recentCheck = JSON.stringify({
+      checkedAt: new Date().toISOString(),
+      latestVersion: '2.20.0',
+    });
+    vi.mocked(fs.readFile).mockResolvedValueOnce(recentCheck);
+
+    const result = await checkForUpdate();
+    expect(result).toBeNull();
+    expect(mockExecFile).not.toHaveBeenCalled();
+  });
+
+  it('re-checks npm when cache is stale (>24h)', async () => {
+    const staleCheck = JSON.stringify({
+      checkedAt: new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString(),
+      latestVersion: '2.20.0',
+    });
+    vi.mocked(fs.readFile).mockResolvedValueOnce(staleCheck);
+    mockExecFile.mockResolvedValueOnce({ stdout: '2.22.0\n', stderr: '' });
+
+    const result = await checkForUpdate();
+    expect(result).toContain('2.22.0');
+    expect(mockExecFile).toHaveBeenCalled();
+  });
+
+  it('returns null when current is newer than latest (dev version)', async () => {
+    vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));
+    mockExecFile.mockResolvedValueOnce({ stdout: '2.19.0\n', stderr: '' });
+
+    const result = await checkForUpdate();
+    expect(result).toBeNull();
+  });
+});

package/src/utils/version-check.ts

@@ -0,0 +1,96 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { CACHE_DIR, getPackageVersion } from './config';
+
+const execFileAsync = promisify(execFile);
+
+const VERSION_CHECK_FILE = path.join(CACHE_DIR, 'last-version-check.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+interface VersionCheckCache {
+  checkedAt: string;
+  latestVersion: string;
+}
+
+function compareVersions(current: string, latest: string): number {
+  const a = current.split('.').map(Number);
+  const b = latest.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] || 0) < (b[i] || 0)) return -1;
+    if ((a[i] || 0) > (b[i] || 0)) return 1;
+  }
+  return 0;
+}
+
+async function loadCache(): Promise<VersionCheckCache | null> {
+  try {
+    const content = await fs.readFile(VERSION_CHECK_FILE, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+async function saveCache(cache: VersionCheckCache): Promise<void> {
+  try {
+    await fs.mkdir(CACHE_DIR, { recursive: true });
+    await fs.writeFile(VERSION_CHECK_FILE, JSON.stringify(cache), 'utf-8');
+  } catch {
+    // Silently ignore cache write failures
+  }
+}
+
+async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync('npm', ['view', '@nemus-cli/nemus', 'version'], {
+      timeout: 5000,
+    });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a newer version is available.
+ * Returns upgrade message string if an update is available, null otherwise.
+ * Caches the result for 24 hours to avoid spamming npm on every invocation.
+ * This is designed to be non-blocking and best-effort — failures are silent.
+ */
+export async function checkForUpdate(): Promise<string | null> {
+  try {
+    const currentVersion = getPackageVersion();
+    const cache = await loadCache();
+
+    // If we checked recently, use cached result
+    if (cache) {
+      const elapsed = Date.now() - new Date(cache.checkedAt).getTime();
+      if (elapsed < CHECK_INTERVAL_MS) {
+        if (compareVersions(currentVersion, cache.latestVersion) < 0) {
+          return formatUpdateMessage(currentVersion, cache.latestVersion);
+        }
+        return null;
+      }
+    }
+
+    // Fetch latest version from npm (async with timeout)
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) return null;
+
+    await saveCache({ checkedAt: new Date().toISOString(), latestVersion });
+
+    if (compareVersions(currentVersion, latestVersion) < 0) {
+      return formatUpdateMessage(currentVersion, latestVersion);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function formatUpdateMessage(current: string, latest: string): string {
+  return `\x1b[33m[nemus] Update available: ${current} -> ${latest}. Run: npm install -g @nemus-cli/nemus@latest\x1b[0m`;
+}

package/src/utils/workspace-meta.ts

@@ -0,0 +1,173 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { WorkspaceMetadata, RepositoryMetadata, CloneResult } from '../types';
+import { logSuccess, logWarning, logError } from './logger';
+import { WORKSPACES_DIR, META_FILENAME, getCloneUrl } from './config';
+import { safeWorkspacePath } from './validation';
+
+const ARCHIVE_EXPIRY_DAYS = 30;
+
+export const createMetadata = (
+  workspaceName: string,
+  cloneResults: CloneResult[],
+  options?: { prompt?: string }
+): WorkspaceMetadata => {
+  const repositories: RepositoryMetadata[] = cloneResults.map(result => ({
+    name: result.repo.name,
+    directoryName: result.directoryName,
+    owner: result.repo.owner.login,
+    clonedAt: result.clonedAt || new Date().toISOString(),
+    cloneUrl: getCloneUrl(result.repo),
+    status: result.status,
+    error: result.error,
+  }));
+
+  return {
+    workspaceName,
+    createdAt: new Date().toISOString(),
+    repositories,
+    ...(options?.prompt ? { prompt: options.prompt } : {}),
+  };
+};
+
+export const saveMetadata = async (
+  workspacePath: string,
+  metadata: WorkspaceMetadata
+): Promise<void> => {
+  try {
+    const metaPath = path.join(workspacePath, META_FILENAME);
+    await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2), 'utf-8');
+    logSuccess('Saved workspace metadata');
+  } catch (error) {
+    logWarning('Failed to save workspace metadata');
+    if (error instanceof Error) {
+      logError(error.message);
+    }
+  }
+};
+
+export const loadMetadata = async (workspacePath: string): Promise<WorkspaceMetadata | null> => {
+  try {
+    const metaPath = path.join(workspacePath, META_FILENAME);
+    const content = await fs.readFile(metaPath, 'utf-8');
+    const metadata: WorkspaceMetadata = JSON.parse(content);
+
+    // Backward compatibility: default directoryName to name for old entries
+    for (const repo of metadata.repositories) {
+      if (!repo.directoryName) {
+        repo.directoryName = repo.name;
+      }
+    }
+
+    return metadata;
+  } catch {
+    return null;
+  }
+};
+
+export const listWorkspaces = async (
+  includeArchived: boolean = false
+): Promise<Array<{ name: string; path: string; metadata: WorkspaceMetadata | null }>> => {
+  try {
+    await fs.access(WORKSPACES_DIR);
+  } catch {
+    return [];
+  }
+
+  try {
+    // Lazily purge expired archives on every list call
+    await purgeExpiredArchives();
+
+    const entries = await fs.readdir(WORKSPACES_DIR, { withFileTypes: true });
+    const workspaces = [];
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const workspacePath = path.join(WORKSPACES_DIR, entry.name);
+        const metadata = await loadMetadata(workspacePath);
+
+        // Filter based on archive status
+        if (!includeArchived && metadata?.archivedAt) {
+          continue;
+        }
+
+        workspaces.push({
+          name: entry.name,
+          path: workspacePath,
+          metadata,
+        });
+      }
+    }
+
+    return workspaces;
+  } catch (error) {
+    logError('Failed to list workspaces');
+    return [];
+  }
+};
+
+export const archiveWorkspace = async (workspaceName: string): Promise<void> => {
+  const workspacePath = safeWorkspacePath(workspaceName);
+  const metadata = await loadMetadata(workspacePath);
+
+  if (!metadata) {
+    throw new Error(`Workspace not found: ${workspaceName}`);
+  }
+
+  if (metadata.archivedAt) {
+    throw new Error(`Workspace is already archived: ${workspaceName}`);
+  }
+
+  metadata.archivedAt = new Date().toISOString();
+  await saveMetadata(workspacePath, metadata);
+};
+
+export const unarchiveWorkspace = async (workspaceName: string): Promise<void> => {
+  const workspacePath = safeWorkspacePath(workspaceName);
+  const metadata = await loadMetadata(workspacePath);
+
+  if (!metadata) {
+    throw new Error(`Workspace not found: ${workspaceName}`);
+  }
+
+  if (!metadata.archivedAt) {
+    throw new Error(`Workspace is not archived: ${workspaceName}`);
+  }
+
+  delete metadata.archivedAt;
+  await saveMetadata(workspacePath, metadata);
+};
+
+export const purgeExpiredArchives = async (): Promise<void> => {
+  try {
+    await fs.access(WORKSPACES_DIR);
+  } catch {
+    return;
+  }
+
+  try {
+    const entries = await fs.readdir(WORKSPACES_DIR, { withFileTypes: true });
+    const now = Date.now();
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const workspacePath = path.join(WORKSPACES_DIR, entry.name);
+      const metadata = await loadMetadata(workspacePath);
+
+      if (!metadata?.archivedAt) continue;
+
+      const archivedTime = new Date(metadata.archivedAt).getTime();
+      const daysSinceArchive = (now - archivedTime) / (1000 * 60 * 60 * 24);
+
+      if (daysSinceArchive > ARCHIVE_EXPIRY_DAYS) {
+        await fs.rm(workspacePath, { recursive: true, force: true });
+        process.stderr.write(`Purged expired archive: ${entry.name}\n`);
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      process.stderr.write(`Error purging expired archives: ${error.message}\n`);
+    }
+  }
+};